{ "openapi": "3.0.0", "info": { "description": "This is the interface for interacting with the [Asana Platform](https://developers.asana.com). Our API reference is generated from our [OpenAPI spec] (https://raw.githubusercontent.com/Asana/openapi/master/defs/asana_oas.yaml).", "x-public-description": "This is the interface for interacting with the [Asana Platform](https://developers.asana.com). Our API reference is generated from our [OpenAPI spec] (https://raw.githubusercontent.com/Asana/openapi/master/defs/asana_oas.yaml).", "title": "Asana", "termsOfService": "https://asana.com/terms", "contact": { "name": "Asana Support", "url": "https://asana.com/support" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "1.0", "x-docs-schema-whitelist": [ "AsanaResource", "AsanaNamedResource", "AuditLogEvent", "AttachmentResponse", "AttachmentCompact", "BatchResponse", "CustomFieldSettingResponse", "CustomFieldSettingCompact", "CustomTypeResponse", "CustomTypeBase", "CustomTypeCompact", "CustomTypeStatusOptionResponse", "CustomTypeStatusOptionBase", "CustomTypeStatusOptionCompact", "CustomFieldResponse", "CustomFieldCompact", "CustomFieldMembershipCompact", "CustomFieldMembershipResponse", "EnumOption", "EventResponse", "ErrorResponse", "GoalResponse", "GoalCompact", "GoalMembershipCompact", "GoalMembershipBase", "GoalMembershipResponse", "GoalRelationshipResponse", "GoalRelationshipCompact", "GraphExportResponse", "GraphExportCompact", "JobResponse", "JobCompact", "OrganizationExportResponse", "OrganizationExportCompact", "PortfolioMembershipResponse", "PortfolioMembershipCompact", "PortfolioResponse", "PortfolioCompact", "ProjectBriefResponse", "ProjectBriefCompact", "ProjectMembershipCompactResponse", "ProjectMembershipNormalResponse", "ProjectMembershipCompact", "ProjectResponse", "ProjectCompact", "ProjectStatusResponse", "ProjectStatusCompact", "ProjectTemplateCompact", "ProjectTemplateResponse", "RuleTriggerResponse", "ResourceExportResponse", "ResourceExportCompact", "SectionResponse", "SectionCompact", "StatusUpdateResponse", "StatusUpdateCompact", "StoryResponse", "StoryCompact", "TagResponse", "TagCompact", "TaskResponse", "TaskCompact", "TaskCountResponse", "TeamMembershipResponse", "TeamMembershipCompact", "TeamResponse", "TeamCompact", "TimePeriodResponse", "TimePeriodCompact", "UserTaskListResponse", "UserTaskListCompact", "UserResponse", "UserCompact", "WebhookFilter", "WebhookResponse", "WebhookCompact", "WorkspaceMembershipResponse", "WorkspaceMembershipCompact", "WorkspaceResponse", "WorkspaceCompact" ] }, "servers": [ { "url": "https://app.asana.com/api/1.0", "description": "Main endpoint." } ], "security": [ { "personalAccessToken": [] }, { "oauth2": [] } ], "x-readme": { "proxy-enabled": false }, "tags": [ { "name": "Allocations", "description": "An allocation object represents how much of a resource (e.g. person, team) is dedicated to a specific work object (e.g. project, portfolio) over a specific period of time. The effort value of an allocation object can be a percentage or number of hours." }, { "name": "Access requests", "description": "An access request object represents a user's request to an item, such as a project or portfolio, that they do not have access to. The request is sent to the owner of the item for approval." }, { "name": "Attachments", "description": "An *attachment* object represents any file attached to a task in Asana, whether it's an uploaded file or one associated via a third-party service such as Dropbox or Google Drive." }, { "name": "Audit log API", "description": "Asana's audit log is an immutable log of [important events](/docs/audit-log-events#supported-audit-log-events) in your organization's Asana instance.\n\nThe audit log API allows you to monitor and act upon important security and compliance-related changes. Organizations might use this API endpoint to:\n\n* Set up proactive alerting with a Security Information and Event Management (SIEM) tool like [Splunk](https://asana.com/guide/help/api/splunk)\n* Conduct reactive investigations when a security incident takes place\n* Visualize key domain data in aggregate to identify security trends\n\nNote that since the API provides insight into what is happening in an Asana instance, the data is [read-only](/reference/getauditlogevents). That is, there are no \"write\" or \"update\" endpoints for audit log events.\n\nOnly [Service Accounts](https://asana.com/guide/help/premium/service-accounts) in [Enterprise Domains](https://asana.com/enterprise) can access audit log API endpoints. Authentication with a Service Account's [personal access token](/docs/personal-access-token) is required.\n\nFor a full list of supported events, see [supported AuditLogEvents](/docs/audit-log-events#supported-audit-log-events)." }, { "name": "Batch API", "description": "There are many cases where you want to accomplish a variety of work in the Asana API but want to minimize the number of HTTP requests you make. For example:\n\n* Modern browsers limit the number of requests that a single web page can\n make at once.\n* Mobile apps will use more battery life to keep the cellular radio on\n when making a series of requests.\n* There is an overhead cost to developing software that can make multiple\n requests in parallel.\n* Some cloud platforms handle parallelism poorly, or disallow it\n entirely.\n\n\nTo make development easier in these use cases, Asana provides a **batch API** that enables developers to perform multiple \u201cactions\u201d by making only a single HTTP request.\n\n#### Making a batch request\n\nTo make a batch request, send a `POST` request to `/batch`. Like other `POST` endpoints, the body should contain a `data` envelope. Inside this envelope should be a single `actions` field, containing a list of \u201caction\u201d objects. Each action represents a standard request to an existing endpoint in the Asana API.\n\n**The maximum number of actions allowed in a single batch request is 10**. Making a batch request with no actions in it will result in a `400 Bad Request`.\n\nWhen the batch API receives the list of actions to execute, it will dispatch those actions to the already-implemented endpoints specified by the `relative_path` and `method` for each action. This happens in parallel, so all actions in the request will be processed simultaneously. There is no guarantee of the execution order for these actions, nor is there a way to use the output of one action as the input of another action (such as creating a task and then commenting on it).\n\nThe response to the batch request will contain (within the `data` envelope) a list of result objects, one for each action. The results are guaranteed to be in the same order as the actions in the request (e.g., the first result in the response corresponds to the first action in the request)\n\nThe batch API will always attempt to return a `200 Success` response with individual result objects for each individual action in the request. Only in certain cases (such as missing authorization or malformed JSON in the body) will the entire request fail with another status code. Even if every individual action in the request fails, the batch API will still return a `200 Success` response, and each result object in the response will contain the errors encountered with each action.\n\n#### Rate limiting\n\nThe batch API fully respects all of our rate limiting. This means that a batch request counts against *both* the standard rate limiter and the concurrent request limiter as though you had made a separate HTTP request for every individual action. For example, a batch request with five actions counts as five separate requests in the standard rate limiter, and counts as five concurrent requests in the concurrent request limiter. The batch request itself incurs no cost.\n\nIf any of the actions in a batch request would exceed any of the enforced limits, the *entire* request will fail with a `429 Too Many Requests` error. This is to prevent the unpredictability of which actions might succeed if not all of them could succeed.\n\n#### Restrictions\n\nNot every endpoint can be accessed through the batch API. Specifically, the following actions cannot be taken and will result in a `400 Bad Request` for that action:\n\n* Uploading attachments\n* Creating, getting, or deleting organization exports\n* Any SCIM operations\n* Nested calls to the batch API" }, { "name": "Custom fields", "description": "_Note: Custom fields are a premium feature. Integrations which work with custom fields need to handle an assortment of use cases for free and premium users in context of free and premium organizations. For a detailed examination of which data users will have access in different circumstances, review the section below on access control._\n\nIn the Asana application, tasks, projects, and portfolios can hold user-specified [custom fields](https://asana.com/guide/help/premium/custom-fields) which provide extra information (e.g., a \"priority\" property with an associated value, or a number representing the time required to complete a task). This lets a user define the type of information that each item within a project or portfolio can contain in addition to the built-in fields that Asana provides.\n`display_value` is a read-only field that will always be a string. For apps that use custom fields, this is a great way to safely display/export the value of a custom field, regardless of its type. We suggest apps use this field in order to future-proof for changes to custom fields.\n\n#### Characteristics of custom fields\n\n* There is metadata that defines the custom field. This metadata can be shared across an entire workspace, or be specific to a project or portfolio.\n* Creating a custom field setting on a project or portfolio means each direct child will have the custom field. This is conceptually akin to adding columns in a database or a spreadsheet: every task (row) in the project (table) can contain information for that field, including \"blank\" values (i.e., `null` data). For portfolio custom fields, every project (row) in the portfolio (table) will contain information for the custom field.\n* Custom field settings only go one child deep. This means that a custom field setting on a portfolio will give each project the custom field, but not each task within those projects.\n* Tasks have custom field _values_ assigned to them.\n\n#### Types of custom fields\n\nIntegrations using custom fields need to be aware of the six basic types that a custom field can adopt. These types are:\n\n* `text` - an arbitrary, relatively short string of text\n* `number` - a number with a defined level of precision\n* `enum` - a selection of a single option from a defined list of options (i.e., mutually exclusive selections)\n* `multi_enum` - a selection of one or more options from a defined list of options (i.e., mutually inclusive selections)\n* `date` - a reference date with an optional time value\n* `people` - a list of active contributors (i.e., where their relationship to the work is defined in the custom field title)\n\n#### Example use case\n\nConsider an organization that has defined a custom field for \"Priority\". This field is of `enum` type and can have user-defined values of `Low`, `Medium`, or `High`. This is the field metadata, and it is visible within, and shared across, the entire organization.\n\nA project is then created in the organization, called \"Bugs\", and the \"Priority\" custom field is associated with that project. This will allow all tasks within the \"Bugs\" project to have an associated \"Priority\".\n\nA new task is created within \"Bugs\". This task, then, has a field named \"Priority\" which can take on the custom field value of one of `[null]`, `Low`, `Medium`, and `High`.\n\n#### Custom fields in the API\n\nThese custom fields are accessible via the API through a number of endpoints at the top level (e.g. `/custom_fields` and `/custom_field_settings`) and through requests on workspaces, portfolios, projects, and tasks resources. The API also provides a way to fetch both the metadata and data which define each particular custom field, so that a client application may render proper UI to display or edit the values.\n\nText fields are currently limited to 1024 characters. On tasks, their custom field value will have a `text_value` property to represent this field.\n\nNumber fields can have an arbitrary `precision` associated with them; for example, a precision of `2` would round its value to the second (hundredths) place (e.g., `1.2345` would round to `1.23`). On tasks, the custom field value will have a `number_value` property to represent this field.\n\n#### Enum fields\n\nEnum fields represent a selection from a list of options. On the metadata, they will contain all of the options in an array. Each option has 4 properties:\n\n* `gid` - the GID of this enum option. Note that this is the GID of the individual _option_. The custom field itself has a separate `gid`.\n* `name` - the name of the option (e.g., \"Choice #1\")\n* `enabled` - whether this field is enabled. Disabled fields are not available to choose from when disabled, and are visually hidden in the Asana application, but they remain in the metadata for custom field values which were set to the option before the option was disabled.\n* `color` - a color associated with this choice.\n\nOn the task's custom field value, the enum will have an `enum_value` property which will be the same as one of the choices from the list defined in the custom field metadata.\n\n#### Querying an organization for its custom fields\n\nFor custom fields shared across the workspace or organization, the workspace [can be queried](/reference/getcustomfieldsforworkspace) for its list of defined custom fields. Like other collection queries, the fields will be returned as a compact record; slightly different from most other compact records is the fact that the compact record for custom fields includes `type` as well as `gid` and `name`.\n\n#### Accessing custom field definitions\n\nThe [custom fields](/reference/getcustomfield) reference describes how the metadata which defines a custom field is accessed. A GET request with a `gid` can be issued on the `/custom_fields` endpoint to fetch the full definition of a single custom field given its `gid` from (for instance) listing all custom fields on a workspace, or getting the `gid` from a custom field settings object or a task.\n\n#### Associating custom fields with a project or portfolio\n\nA mapping between a custom field and a project or portfolio is handled with a [custom field settings](/reference/custom-field-settings) object. This object contains a reference for each of the custom fields and the project or portfolio, as well as additional information about the status of that particular custom field (e.g., `is_important`, which defines whether or not the custom field will appear in the list/grid on the Asana application).\n\n#### Accessing custom field values on tasks or projects\n\nThe [tasks](/reference/gettask) reference has information on how custom fields look on tasks. custom fields will return as an array on the property `custom_fields`, and each entry will contain, side-by-side, the compact representation of the custom field metadata and a `{typename}_value` property that stores the value set for the custom field.\n\nOf particular note is that the top-level `gid` of each entry in the `custom_fields` array is the `gid` of the custom field metadata, as it is the compact representation of this metadata. This can be used to refer to the full metadata by making a request to the `/custom_fields/{custom_fields_id}` endpoint as described above.\n\nCustom fields can be set just as in the Asana-defined fields on a task via `POST` or `PUT` requests. You can see an example in the [update a task](/reference/updatetask) endpoint.\n\nCustom fields on projects follow this same pattern.\n\n#### Warning: Program defensively with regards to custom field definitions\n\nAsana application users have the ability to change the definitions of custom field metadata. This means that as you write scripts or applications to work with them, it is possible for the definitions to change at any time, which may cause an application using them to break or malfunction if it makes assumptions about the metadata for a particular custom field. When using custom fields, it is a good idea to program *defensively*, meaning you your application should double-check that the custom field metadata are what it expects.\n\nStoring the state of the custom field metadata for too long if you dynamically create a model for it can cause your model to become out of sync with the model stored in Asana. For example, if you encounter an `enum` value on a task that does not match any option in your metadata model, your metadata model has become out of date with the custom field metadata.\n\n#### Enabled and disabled values\n\nWhen information that is contained in a custom field value loses a logical association with its metadata definition, the value becomes disabled. This can happen in a couple of simple ways, for example, if you remove the custom field metadata from a project, or move a task with a custom field to a different project which does not have the custom field metadata associated with it. The value remains on the task, and the custom field metadata can still be found and examined, but as the context in which the custom field makes sense is gone, the custom field cannot change its value; it can only be cleared.\n\n_Note: Tasks that are associated with multiple projects do not become disabled, so long as at least one of the projects is still associated with the custom field metadata. In other words, tasks with multiple projects will retain logically associated to the set of custom field metadata represented by all of their projects._\n\nMoving the task back under a project with that custom field applied to it or applying the custom field metadata to the current project will return the custom field value to an enabled state. In this scenario, the custom field will be re-enabled and editable again.\n\nIn the Asana application, disabled fields are grayed out and not allowed to change, other than to be discarded. In the API, we return a property `enabled: false` to inform the external application that the value has been disabled.\n\nNote that the API enforces the same operations on disabled custom field values as hold in the Asana application: they may not have their values changed, since the lack of context for the values of a custom field in general doesn't provide enough information to know what new values should be. Setting the custom field value to `null` will clear and remove the custom field value from the task.\n\n#### Custom field access control\n\nCustom fields are a complex feature of the Asana platform, and their access in the Asana application and in the API vary based on the status of the user and project. When building your application, it is best to be defensive and not assume the given user will have read or write access to a custom field, and fail gracefully when this occurs." }, { "name": "Custom field settings", "description": "Custom fields are attached to a particular project with the custom field settings resource. This resource both represents the many-to-many join of the custom field and project as well as stores information that is relevant to that particular pairing. For instance, the `is_important` property determines some possible application-specific handling of that custom field." }, { "name": "Custom types", "description": "A custom type allows distinct categorizations of objects based on their specific purpose or functionality. Structuring objects through a defined custom type provides greater flexibility in work management allowing users to better match the object to their use case" }, { "name": "Events", "description": "An event is an object representing a change to a resource that was observed by an event subscription. Event streams rely on the same infrastructure as webhooks, which ensures events are delivered within a minute (on average). This system is designed for at most once delivery, meaning in exceptional circumstances a small number of events may be missing from the stream. For this reason, if your use case requires strong guarantees about processing all changes on a resource and cannot tolerate any missing events, regardless of how rare that might be, we recommend building a fallback polling system that fetches the resource periodically as well. Note that while webhooks cannot be replayed once delivered, events are retrievable from the event stream for 24 hours after being processed.\n\nIn general, requesting events on a resource is faster and subject to higher rate limits than requesting the resource itself. Additionally, change events \"bubble up\" (e.g., listening to events on a project would include when stories are added to tasks in the project, and even to subtasks).\n\nEstablish an initial sync token by making a request with no sync token. The response will be a `412 Precondition Failed` error - the same as if the sync token had expired.\n\nSubsequent requests should always provide the sync token from the immediately preceding call.\n\nSync tokens may not be valid if you attempt to go \"backward\" in the history by requesting previous tokens, though re-requesting the current sync token is generally safe, and will always return the same results.\n\nWhen you receive a `412 Precondition Failed` error, it means that the sync token is either invalid or expired. If you are attempting to keep a set of data in sync, this signals you may need to re-crawl the data.\n\nSync tokens always expire after 24 hours, but may expire sooner, depending on load on the service." }, { "name": "Exports", "description": "Exports are a way to download data from Asana. The following types of exports are available:\n* **Graph exports**: Export of data about objects starting from a parent object, such as a team, portfolio, or project.\n* **Resource exports**: Bulk exports of resources such as tasks, teams, and messages for a workspace.\n* **Organization exports**: Exports the complete data of an organization in JSON format. Please refer to [Organization exports](/reference/organization-exports) for more details.\n\n## Graph exports\nA `graph_export` object represents a request to export the\ndata about objects starting from a parent object. Parent object can be a team, portfolio, or project.\n\nTo create an export using this API:\n1. Create a `graph_export` [request](/reference/createGraphExport) and store the ID that is returned.\n2. Request the [jobs](/reference/getjob) endpoint every few minutes, until `status` field contains 'succeeded'.\n3. Download the file located at the URL in the `download_url` field.\n\nExports can take a long time, from several minutes to a few hours for large portfolios.\n\n*Note: Graph exports are only available to accounts of an\n[Enterprise](https://asana.com/enterprise)/Enterprise+ organization.*\n\n## Resource exports\nA `resource_export` object represents a request to bulk export resources for a workspace.\nTo create an export using this API:\n1. Create a `resource_export` [request](/reference/createResourceExport) and store the job ID that is returned.\n2. Request the [jobs](/reference/getjob) endpoint at some interval, until `status` field contains 'succeeded' and a `download_url` is available.\n3. Download the file located at the URL in the `download_url` field.\n\nExports can take a long time, from several minutes to a few hours for large workspaces.\n\n*Note: Resource exports are only available to [Service Accounts](https://asana.com/guide/help/premium/service-accounts)\nfrom an Enterprise+ organization or an organization with the Compliance Management Add-on." }, { "name": "Goals", "description": "A goal is an object in the goal-tracking system that helps your organization drive measurable results." }, { "name": "Goal relationships", "description": "A goal relationship is an object representing the relationship between a goal and another goal, a project, a task, or a portfolio." }, { "name": "Jobs", "description": "Jobs represent processes that handle asynchronous work. A job created when an endpoint requests an action that will be handled asynchronously, such as project or task duplication.\n\nOnly the creator of the duplication process can access the duplication status of the new object.\n\n*Note*: With any work that is handled asynchronously (e.g., [project instantation from a template](/reference/instantiateproject), duplicating a [task](/reference/duplicatetask) or [project](/reference/duplicateproject), etc.), the *intermittent states* of newly-created objects may not be consistent. That is, object properties may return different values each time when polled until the job `status` has returned a `succeeded` value." }, { "name": "Memberships", "description": "A membership object represents the relationship between a team or user and an object in Asana. Currently, the\nsupported types of memberships are for goals, projects, and portfolios. For example, a project membership\ncan be used to add a user to a project." }, { "name": "Organization exports", "description": "An `organization_export` object represents a request to export the complete data of an organization in JSON format.\n\nTo export an organization using this API:\n\n* Create an `organization_export`\n [request](/reference/createorganizationexport)\n and store the ID that is returned.\n* Request the `organization_export` every few minutes, until the\n `state` field contains \u2018finished\u2019.\n* Download the file located at the URL in the `download_url` field. * Exports can take a long time, from several minutes to a few hours\n for large organizations.\n\n\n*Note: These endpoints are only available to [Service Accounts](https://asana.com/guide/help/premium/service-accounts) of an [Enterprise](https://asana.com/enterprise) organization.*" }, { "name": "Portfolios", "description": "A portfolio gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [status update](/reference/status-updates).\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a maximum of 20 custom fields." }, { "name": "Portfolio memberships", "description": "This object determines if a user is a member of a portfolio." }, { "name": "Projects", "description": "A project represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. A project exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.\n\nProjects in organizations are shared with a single team. Currently, the team of a project cannot be changed via the API. Non-organization workspaces do not have teams and so you should not specify the team of project in a regular workspace.\n\nFollowers of a project are a subset of the members of that project. Followers of a project will receive all updates including tasks created, added and removed from that project. Members of the project have access to and will receive status updates of the project. Adding followers to a project will add them as members if they are not already, removing followers from a project will not affect membership.\n\n**Note:** You can use certain project endpoints to operate on [user task lists](/reference/user-task-lists) ([My Tasks](https://asana.com/guide/help/fundamentals/my-tasks)) by substituting the `{project_gid}` with the `{user_task_list_gid}`. For example, you can perform operations on the custom fields of a user task list by using the following projects endpoints: [Add a custom field to a project](/reference/addcustomfieldsettingforproject), [Remove a custom field from a project](/reference/removecustomfieldsettingforproject) and [Get a project's custom fields](/reference/getcustomfieldsettingsforproject)" }, { "name": "Project briefs", "description": "A project brief object represents a rich text document that describes a project.\n\nPlease note that this API is in *preview*, and is expected to change. This API is to be used for development and testing only as an advance view into the upcoming rich text format experience in the task description. For more information, see [this post](https://forum.asana.com/t/project-brief-api-now-available-as-a-preview/150885) in the developer forum." }, { "name": "Project memberships", "description": "With the introduction of \u201ccomment-only\u201d projects in Asana, a user\u2019s membership in a project comes with associated permissions. These permissions (i.e., whether a user has full access to the project or comment-only access) are accessible through the project memberships endpoints described here." }, { "name": "Project statuses", "description": "*Deprecated: new integrations should prefer using [status updates](/reference/status-updates)*\n\nA project status is an update on the progress of a particular project,\nand is sent out to all project followers when created. These updates\ninclude both text describing the update and a color code intended to\nrepresent the overall state of the project: \"green\" for projects that\nare on track, \"yellow\" for projects at risk, \"red\" for projects that\nare behind, and \"blue\" for projects on hold.\n\nProject statuses can be created and deleted, but not modified." }, { "name": "Project templates", "description": "A project template is an object that allows new projects to be created\nwith a predefined setup, which may include tasks, sections, rules, etc.\nIt simplifies the process of running a workflow that involves a similar\nset of work every time.\n\n\nProject templates in organizations are shared with a single team. Currently, the\nteam of a project template cannot be changed via the API." }, { "name": "Reactions", "description": "A reaction is an object that represents a user's emoji reaction on a status update, comment, task completion, or attachment." }, { "name": "Rules", "description": "[Asana rules](https://help.asana.com/s/article/rules?language=en_US) allow you to automate common patterns\nand workflows in Asana. Rules comprise triggers that will automatically perform actions. For example, you\ncan create a rule to automatically assign a task (action) when a due date is set (trigger).\n\nTo support cross-application workflows, the API supports\n[incoming web requests](https://developers.asana.com/docs/incoming-web-requests) as a generic trigger to\nconnect external applications to Asana through rules. This API allows users to set up workflows outside\nof Asana that can perform operations on data within Asana." }, { "name": "Sections", "description": "A section is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.\n\nSections are largely a shared idiom in Asana\u2019s API for both list and board views of a project regardless of the project\u2019s layout.\n\nThe \u2018memberships\u2019 property when [getting a task](/reference/gettask) will return the information for the section or the column under \u2018section\u2019 in the response." }, { "name": "SSPM", "description": "SSPM (SaaS Security Posture Management) is a set of APIs which allows centralized inspection and management of a customer's deployed SaaS apps via an SSPM provider." }, { "name": "Status updates", "description": "A status update is an update on the progress of a particular object,\nand is sent out to all followers when created. These updates\ninclude both text describing the update and a `status_type` intended to\nrepresent the overall state of the project. These include: `on_track` for projects that\nare on track, `at_risk` for projects at risk, `off_track` for projects that\nare behind, and `on_hold` for projects on hold.\n\nStatus updates can be created and deleted, but not modified." }, { "name": "Stories", "description": "*See [our forum post](https://forum.asana.com/t/no-more-parsing-story-text-new-fields-on-stories/42924) for more info on when conditional fields are returned.*\n\nA story represents an activity associated with an object in the Asana system. Stories are generated by the system whenever users take actions such as creating or assigning tasks, or moving tasks between projects. \"Comments\" are also a form of user-generated story." }, { "name": "Tags", "description": "A tag is a label that can be attached to any task in Asana. It exists in a single workspace or organization.\n\nTags have some metadata associated with them, but it is possible that we will simplify them in the future so it is not encouraged to rely too heavily on it. Unlike projects, tags do not provide any ordering on the tasks they are associated with." }, { "name": "Tasks", "description": "The task is the basic object around which many operations in Asana are centered. In the Asana application, multiple tasks populate the middle pane according to some view parameters, and the set of selected tasks determines the more detailed information presented in the details pane.\n\nSections are unique in that they will be included in the `memberships` field of task objects returned in the API when the task is within a section. They can also be used to manipulate the ordering of a task within a project.\n\n[Queries](/reference/gettasks) return a [compact representation of each task object](/reference/tasks). To retrieve *all* fields or *specific set* of the fields, use [field selectors](/docs/inputoutput-options) to manipulate what data is included in a response." }, { "name": "Task templates", "description": "A task template is an object that allows new tasks to be created with a predefined setup, which may include followers, dependencies, custom fields, etc. It simplifies the process of running a workflow that involves a similar set of work every time.\nTask templates are contained within a single project." }, { "name": "Teams", "description": "A team is used to group related projects and people together within an organization. Each project in an organization is associated with a team." }, { "name": "Team memberships", "description": "This object determines if a user is a member of a team." }, { "name": "Time periods", "description": "A time period is an object that represents a domain-scoped date range that can be set on [goals](/reference/goals)." }, { "name": "Time tracking entries", "description": "Asana\u2019s native time tracking feature allows you to estimate the time needed to complete a task, as well as record the actual time spent." }, { "name": "Typeahead", "description": "The typeahead search API provides search for objects from a single workspace." }, { "name": "Users", "description": "A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.\n\nLike other objects in the system, users are referred to by numerical IDs. However, the special string identifier `me` can be used anywhere a user ID is accepted, to refer to the current authenticated user (e.g, `GET /users/me`)." }, { "name": "User task lists", "description": "A user task list represents the tasks assigned to a particular user. This list is the user's [My Tasks](https://asana.com/guide/help/fundamentals/my-tasks) list." }, { "name": "Webhooks", "description": "Webhooks allow you to subscribe to notifications about events that occur on Asana resources (e.g., tasks, projects, stories, etc.).\n\nFor a more detailed explanation of webhooks see the [overview of webhooks](/docs/webhooks-guide)." }, { "name": "Workspaces", "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.\n\nAn *organization* is a special kind of workspace that represents a company. In an organization, you can group your projects into teams. You can read more about how organizations work on the Asana Guide. To tell if your workspace is an organization or not, check its `is_organization` property.\n\nOver time, we intend to migrate most workspaces into organizations and to release more organization-specific functionality. We may eventually deprecate using workspace-based APIs for organizations. Currently, and until after some reasonable grace period following any further announcements, you can still reference organizations in any `workspace` parameter." }, { "name": "Workspace memberships", "description": "This object determines if a user is a member of a workspace." } ], "components": { "parameters": { "fields": { "name": "opt_fields", "in": "query", "description": "Defines fields to return.\nSome requests return *compact* representations of objects in order to conserve resources and complete the request more efficiently. Other times requests return more information than you may need. This option allows you to list the exact set of fields that the API should be sure to return for the objects. The field names should be provided as paths, described below.\nThe id of included objects will always be returned, regardless of the field options.", "example": [ "followers", "assignee" ], "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, "pretty": { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, "limit": { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, "offset": { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, "archived_query_param": { "name": "archived", "in": "query", "description": "Only return projects whose `archived` field takes on the value of this parameter.", "schema": { "type": "boolean" }, "example": false }, "access_request_gid": { "name": "access_request_gid", "in": "path", "description": "Globally unique identifier for the access request.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "access_request" }, "attachment_path_gid": { "name": "attachment_gid", "in": "path", "description": "Globally unique identifier for the attachment.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "attachment" }, "custom_field_path_gid": { "name": "custom_field_gid", "in": "path", "description": "Globally unique identifier for the custom field.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "custom_field" }, "custom_id": { "name": "custom_id", "in": "path", "description": "Generated custom ID for a task.", "required": true, "schema": { "type": "string" }, "example": "EX-1" }, "custom_type_gid": { "name": "custom_type_gid", "in": "path", "description": "Globally unique identifier for the custom type.", "required": true, "schema": { "type": "string" }, "example": "12345" }, "goal_path_gid": { "name": "goal_gid", "in": "path", "description": "Globally unique identifier for the goal.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "goal" }, "goal_relationship_path_gid": { "name": "goal_relationship_gid", "in": "path", "description": "Globally unique identifier for the goal relationship.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "goal_relationship" }, "job_path_gid": { "name": "job_gid", "in": "path", "description": "Globally unique identifier for the job.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "job" }, "membership_path_gid": { "name": "membership_gid", "in": "path", "description": "Globally unique identifier for the membership.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "membership" }, "organization_export_path_gid": { "name": "organization_export_gid", "in": "path", "description": "Globally unique identifier for the organization export.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "organization_export" }, "project_brief_path_gid": { "name": "project_brief_gid", "in": "path", "description": "Globally unique identifier for the project brief.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "project_brief" }, "project_path_gid": { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, "project_query_param": { "name": "project", "in": "query", "description": "Globally unique identifier for the project, which is used as a filter when retrieving all custom types.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, "project_template_path_gid": { "name": "project_template_gid", "in": "path", "description": "Globally unique identifier for the project template.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project_template" }, "project_membership_path_gid": { "name": "project_membership_gid", "in": "path", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project_membership" }, "project_status_path_gid": { "name": "project_status_gid", "in": "path", "required": true, "description": "The project status update to get.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "project_status" }, "status_update_path_gid": { "name": "status_update_gid", "in": "path", "required": true, "description": "The status update to get.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "status" }, "portfolio_path_gid": { "name": "portfolio_gid", "in": "path", "description": "Globally unique identifier for the portfolio.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, "portfolio_membership_path_gid": { "name": "portfolio_membership_gid", "in": "path", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "portfolio_membership" }, "portfolio_query_param": { "name": "portfolio", "in": "query", "description": "The portfolio to filter results on.", "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, "rule_trigger_path_gid": { "name": "rule_trigger_gid", "in": "path", "required": true, "description": "The ID of the incoming web request trigger. This value is a path parameter that is automatically generated for the API endpoint.", "schema": { "type": "string" }, "example": "12345", "x-env-variable": "rule" }, "section_path_gid": { "name": "section_gid", "in": "path", "required": true, "description": "The globally unique identifier for the section.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "section" }, "story_path_gid": { "name": "story_gid", "in": "path", "description": "Globally unique identifier for the story.", "required": true, "schema": { "type": "string" }, "example": "35678", "x-env-variable": "story" }, "target_query_param": { "name": "target", "in": "query", "description": "Globally unique identifier for the target object.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "target" }, "tag_path_gid": { "name": "tag_gid", "in": "path", "description": "Globally unique identifier for the tag.", "required": true, "schema": { "type": "string" }, "example": "11235", "x-env-variable": "tag" }, "task_path_gid": { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, "task_template_path_gid": { "name": "task_template_gid", "in": "path", "description": "Globally unique identifier for the task template.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "task_template" }, "team_path_gid": { "name": "team_gid", "in": "path", "description": "Globally unique identifier for the team.", "required": true, "schema": { "type": "string" }, "example": "159874", "x-env-variable": "team" }, "team_query_param": { "name": "team", "in": "query", "description": "The team to filter projects on.", "schema": { "type": "string" }, "example": "14916", "x-env-variable": "team" }, "team_membership_path_gid": { "name": "team_membership_gid", "in": "path", "required": true, "schema": { "type": "string" }, "example": "724362", "x-env-variable": "team_membership" }, "time_period_path_gid": { "name": "time_period_gid", "in": "path", "description": "Globally unique identifier for the time period.", "required": true, "schema": { "type": "string" }, "example": "917392", "x-env-variable": "time_period" }, "time_tracking_entry_path_gid": { "name": "time_tracking_entry_gid", "in": "path", "description": "Globally unique identifier for the time tracking entry.", "required": true, "schema": { "type": "string" }, "example": "917392", "x-env-variable": "time_tracking_entry" }, "user_query_param": { "name": "user", "in": "query", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, "user_path_gid": { "name": "user_gid", "in": "path", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "required": true, "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, "user_task_list_path_gid": { "name": "user_task_list_gid", "in": "path", "description": "Globally unique identifier for the user task list.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "user_task_list" }, "webhook_path_gid": { "name": "webhook_gid", "in": "path", "description": "Globally unique identifier for the webhook.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "webhook" }, "workspace_path_gid": { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, "workspace_query_param": { "name": "workspace", "in": "query", "description": "The workspace to filter results on.", "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, "workspace_membership_path_gid": { "name": "workspace_membership_gid", "in": "path", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace_membership" }, "audit_log_start_at": { "name": "start_at", "in": "query", "description": "Filter to events created after this time (inclusive).", "required": false, "schema": { "type": "string", "format": "date-time" } }, "audit_log_end_at": { "name": "end_at", "in": "query", "description": "Filter to events created before this time (exclusive).", "required": false, "schema": { "type": "string", "format": "date-time" } }, "audit_log_event_type": { "name": "event_type", "in": "query", "description": "Filter to events of this type.\nRefer to the [supported audit log events](/docs/audit-log-events#supported-audit-log-events) for a full list of values.", "required": false, "schema": { "type": "string" } }, "audit_log_actor_type": { "name": "actor_type", "in": "query", "description": "Filter to events with an actor of this type.\nThis only needs to be included if querying for actor types without an ID. If `actor_gid` is included, this should be excluded.", "required": false, "schema": { "type": "string", "enum": [ "user", "asana", "asana_support", "anonymous", "external_administrator" ] } }, "audit_log_actor_gid": { "name": "actor_gid", "in": "query", "description": "Filter to events triggered by the actor with this ID.", "required": false, "schema": { "type": "string" } }, "audit_log_resource_gid": { "name": "resource_gid", "in": "query", "description": "Filter to events with this resource ID.", "required": false, "schema": { "type": "string" } }, "completed_since": { "name": "completed_since", "in": "query", "required": false, "description": "Only return tasks that are either incomplete or that have been completed since this time. Accepts a date-time string or the keyword *now*.\n", "schema": { "type": "string" }, "example": "2012-02-22T02:06:58.158Z" }, "member": { "name": "member", "in": "query", "required": false, "description": "Member object gid can be user or team.\n", "schema": { "type": "string" }, "example": "123" }, "message_path_gid": { "name": "message_gid", "in": "path", "required": true, "description": "The message to get.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "message" }, "allocation_path_gid": { "name": "allocation_gid", "in": "path", "description": "Globally unique identifier for the allocation.", "required": true, "schema": { "type": "string" }, "example": "77688", "x-env-variable": "allocation" } }, "responses": { "GenericErrorResponse": { "description": "Sadly, sometimes requests to the API are not successful. Failures can occur for a wide range of reasons. In all cases, the API should return an HTTP Status Code that indicates the nature of the failure, with a response body in JSON format containing additional information. In the event of a server error the response body will contain an error phrase. These phrases are automatically generated using the [node-asana-phrase library](https://github.com/Asana/node-asana-phrase) and can be used by Asana support to quickly look up the incident that caused the server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadRequest": { "description": "This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "A valid authentication token was not provided with the request, so the API could not associate a user with the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PaymentRequired": { "description": "The request was valid, but the queried object or object mutation specified in the request is above your current premium level.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "The authentication and request syntax was valid but the server is refusing to complete the request. This can happen if you try to read or write to objects or properties that the user does not have access to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequests": { "description": "You have exceeded one of the enforced rate limits in the API. See the [documentation on rate limiting](https://developers.asana.com/docs/#rate-limits) for more information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerError": { "description": "There was a problem on Asana\u2019s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadGateway": { "description": "There is an issue between the load balancers and Asana's API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServiceUnavailable": { "description": "Either the upstream service is unavailable to the API, or the API has been intentionally shut off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "GatewayTimeout": { "description": "This request took too long to complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "AllocationBase": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "allocation", "x-insert-after": "gid" }, "start_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation starts.", "example": "2024-02-28" }, "end_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation ends.", "example": "2024-02-28" }, "effort": { "type": "object", "nullable": true, "description": "The amount of time associated with the allocation, represented as a percentage or number of hours", "properties": { "type": { "type": "string", "description": "The units used for tracking effort on an allocation, either \"hours\" or \"percent\".", "enum": [ "hours", "percent" ] }, "value": { "type": "number", "description": "The numeric effort value on the allocation.", "example": 50 } } } } }, "AllocationResponse": { "allOf": [ { "$ref": "#/components/schemas/AllocationBase" }, { "type": "object", "properties": { "assignee": { "allOf": [ { "$ref": "#/components/schemas/UserCompact" }, { "type": "object", "description": "The user or placeholder assigned to the allocation.", "properties": { "name": { "type": "string", "description": "The name of allocation resource.", "example": "Greg Sanchez" } } } ] }, "created_by": { "$ref": "#/components/schemas/UserCompact", "type": "object", "description": "The user who created the allocation." }, "parent": { "$ref": "#/components/schemas/ProjectCompact", "type": "object", "description": "The project the allocation is on." }, "resource_subtype": { "description": "The subtype of the allocation.", "type": "string", "example": "project_allocation" } } } ] }, "AllocationRequest": { "allOf": [ { "$ref": "#/components/schemas/AllocationBase" }, { "type": "object", "properties": { "assignee": { "type": "string", "description": "Globally unique identifier for the user or placeholder assigned to the allocation." }, "parent": { "type": "string", "description": "Globally unique identifier for the project the allocation is on." } } } ] }, "AddCustomFieldSettingRequest": { "type": "object", "required": [ "custom_field" ], "properties": { "custom_field": { "oneOf": [ { "type": "string", "description": "The custom field to associate with this container.", "example": "14916" }, { "$ref": "#/components/schemas/CustomFieldCreateRequest" } ] }, "is_important": { "description": "Whether this field should be considered important to this container (for instance, to display in the list view of items in the container).", "type": "boolean", "example": true }, "insert_before": { "description": "A gid of a Custom Field Setting on this container, before which the new Custom Field Setting will be added. `insert_before` and `insert_after` parameters cannot both be specified.", "type": "string", "example": "1331" }, "insert_after": { "description": "A gid of a Custom Field Setting on this container, after which the new Custom Field Setting will be added. `insert_before` and `insert_after` parameters cannot both be specified.", "type": "string", "example": "1331" } } }, "AddFollowersRequest": { "type": "object", "required": [ "followers" ], "properties": { "followers": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "521621,621373" } } }, "AddMembersRequest": { "type": "object", "required": [ "members" ], "properties": { "members": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "521621,621373" } } }, "AsanaNamedResource": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } }, "AsanaResource": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "AttachmentBase": { "$ref": "#/components/schemas/AttachmentCompact" }, "AttachmentCompact": { "description": "An *attachment* object represents any file attached to a task in Asana, whether it's an uploaded file or one associated via a third-party service such as Dropbox or Google Drive.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "attachment", "x-insert-after": "gid" }, "name": { "description": "The name of the file.", "type": "string", "readOnly": true, "example": "Screenshot.png" }, "resource_subtype": { "description": "The service hosting the attachment. Valid values are `asana`, `dropbox`, `gdrive`, `onedrive`, `box`, `vimeo`, and `external`.", "type": "string", "example": "dropbox" } } }, "AttachmentRequest": { "type": "object", "required": [ "parent" ], "properties": { "resource_subtype": { "description": "The type of the attachment. Must be one of the given values. If not specified, a file attachment of type `asana` will be assumed. Note that if the value of `resource_subtype` is `external`, a `parent`, `name`, and `url` must also be provided.\n", "type": "string", "example": "external", "enum": [ "asana", "dropbox", "gdrive", "onedrive", "box", "vimeo", "external" ] }, "file": { "description": "Required for `asana` attachments.\n", "type": "string", "format": "binary" }, "parent": { "description": "Required identifier of the parent task, project, or project_brief, as a string.\n", "type": "string" }, "url": { "description": "The URL of the external resource being attached. Required for attachments of type `external`.\n", "type": "string" }, "name": { "description": "The name of the external resource being attached. Required for attachments of type `external`.\n", "type": "string" }, "connect_to_app": { "description": "*Optional*. Only relevant for external attachments with a parent task.\nA boolean indicating whether the current app should be connected with\nthe attachment for the purposes of showing an app components widget.\nRequires the app to have been added to a project the parent task is in.\nThis property can only be set if an OAuth token is used to authenticate the request.\n\nCriteria for displaying app widget:\n1. An OAuth token must be used to authenticate the request\n2. The app needs to have its `widget_metadata_url` configured in the developer console\n3. The task the attachment is being attached to must be in a project with the app installed", "type": "boolean" } } }, "AttachmentResponse": { "allOf": [ { "$ref": "#/components/schemas/AttachmentBase" }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "The URL containing the content of the attachment.\n*Note:* May be null if the attachment is hosted by [Box](https://www.box.com/) and will be null if the attachment is a Video Message hosted by [Vimeo](https://vimeo.com/). If present, this URL may only be valid for two minutes from the time of retrieval. You should avoid persisting this URL somewhere and just refresh it on demand to ensure you do not keep stale URLs.", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://s3.amazonaws.com/assets/123/Screenshot.png" }, "permanent_url": { "description": "A stable URL for accessing the attachment through the Asana web application. This URL redirects to the file download location (e.g., an S3 link) if the user is authenticated and authorized to view the parent object (e.g., a task). Unauthorized users will receive a `403 Forbidden` response. This link is persistent and does not expire, but requires an active session to resolve.", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://app.asana.com/app/asana/-/get_asset?asset_id=1234567890" }, "host": { "description": "The service hosting the attachment. Valid values are `asana`, `dropbox`, `gdrive`, `box`, and `vimeo`.", "type": "string", "readOnly": true, "example": "dropbox" }, "parent": { "allOf": [ { "$ref": "#/components/schemas/TaskCompact" }, { "type": "object", "nullable": true, "description": "The task this attachment is attached to.", "readOnly": true, "properties": { "resource_subtype": { "description": "The resource subtype of the parent resource that the filter applies to.", "type": "string", "example": "default_task", "nullable": true } } } ] }, "size": { "description": "The size of the attachment in bytes. Only present when the `resource_subtype` is `asana`.", "type": "integer", "readOnly": true, "example": 12345 }, "view_url": { "description": "The URL where the attachment can be viewed, which may be friendlier to users in a browser than just directing them to a raw file. May be null if no view URL exists for the service.", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://www.dropbox.com/s/123/Screenshot.png" }, "connected_to_app": { "description": "Whether the attachment is connected to the app making the request for the purposes of showing an app components widget. Only present when the `resource_subtype` is `external` or `gdrive`.", "type": "boolean", "readOnly": true } } } ] }, "AuditLogEvent": { "description": "An object representing a single event within an Asana domain.\n\nEvery audit log event is comprised of an `event_type`, `actor`, `resource`, and `context`. Some events will include additional metadata about the event under `details`. See our [currently supported list of events](/docs/audit-log-events#supported-audit-log-events) for more details.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the `AuditLogEvent`, as a string.", "type": "string", "example": "12345", "x-insert-after": false }, "created_at": { "description": "The time the event was created.", "type": "string", "format": "date-time", "example": "2021-01-01T00:00:00.000Z" }, "event_type": { "description": "The type of the event.", "type": "string", "example": "task_deleted" }, "event_category": { "description": "The category that this `event_type` belongs to.", "type": "string", "example": "deletion" }, "actor": { "$ref": "#/components/schemas/AuditLogEventActor" }, "resource": { "$ref": "#/components/schemas/AuditLogEventResource" }, "details": { "$ref": "#/components/schemas/AuditLogEventDetails" }, "context": { "$ref": "#/components/schemas/AuditLogEventContext" } } }, "AuditLogEventActor": { "description": "The entity that triggered the event. Will typically be a user.", "type": "object", "properties": { "actor_type": { "description": "The type of actor.\nCan be one of `user`, `asana`, `asana_support`, `anonymous`, or `external_administrator`.", "type": "string", "enum": [ "user", "asana", "asana_support", "anonymous", "external_administrator" ], "example": "user" }, "gid": { "description": "Globally unique identifier of the actor, if it is a user.", "type": "string", "example": "1111" }, "name": { "description": "The name of the actor, if it is a user.", "type": "string", "example": "Greg Sanchez" }, "email": { "description": "The email of the actor, if it is a user.", "type": "string", "example": "gregsanchez@example.com" } } }, "AuditLogEventContext": { "description": "The context from which this event originated.", "type": "object", "properties": { "context_type": { "description": "The type of context.\nCan be one of `web`, `desktop`, `mobile`, `asana_support`, `asana`, `email`, or `api`.", "type": "string", "enum": [ "web", "desktop", "mobile", "asana_support", "asana", "email", "api" ], "example": "web" }, "api_authentication_method": { "description": "The authentication method used in the context of an API request.\nOnly present if the `context_type` is `api`. Can be one of `cookie`, `oauth`, `personal_access_token`, or `service_account`.", "type": "string", "enum": [ "cookie", "oauth", "personal_access_token", "service_account" ] }, "client_ip_address": { "description": "The IP address of the client that initiated the event, if applicable.", "type": "string", "example": "1.1.1.1" }, "user_agent": { "description": "The user agent of the client that initiated the event, if applicable.", "type": "string", "example": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36" }, "oauth_app_name": { "description": "The name of the OAuth App that initiated the event.\nOnly present if the `api_authentication_method` is `oauth`.", "type": "string" }, "rule_name": { "description": "The name of the automation rule that initiated the event.", "type": "string", "example": "When Task is added to this project" }, "on_behalf_of_user_id": { "description": "The ID of the user who requested a change via support.", "type": "integer", "example": 12345 } } }, "AuditLogEventDetails": { "description": "Event specific details. The schema will vary depending on the `event_type`.", "type": "object", "properties": { "old_value": { "description": "The previous value of the field that was modified in the audited event.", "type": "string", "nullable": true }, "new_value": { "description": "The new value after the modification in the audited event.", "type": "string", "nullable": true }, "group": { "description": "The division or organizational unit where the event occurred. Primarily used to scope role change events (e.g., `user_division_admin_role_changed`), but may appear in other contexts involving group-level changes.", "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "AuditLogEventResource": { "description": "The primary object that was affected by this event.", "type": "object", "properties": { "resource_type": { "description": "The type of resource.", "type": "string", "example": "task" }, "resource_subtype": { "description": "The subtype of resource. Most resources will not have a subtype.", "type": "string", "example": "milestone" }, "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "name": { "description": "The name of the resource.", "type": "string", "nullable": true, "example": "Example Task" }, "email": { "description": "The email of the resource, if applicable.", "type": "string" } } }, "BatchRequest": { "description": "A request object for use in a batch request.", "type": "object", "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/BatchRequestAction" } } } }, "BatchRequestAction": { "description": "An action object for use in a batch request.", "type": "object", "properties": { "relative_path": { "description": "The path of the desired endpoint relative to the API\u2019s base URL. Query parameters are not accepted here; put them in `data` instead.", "type": "string", "example": "/tasks/123" }, "method": { "description": "The HTTP method you wish to emulate for the action.", "type": "string", "enum": [ "get", "post", "put", "delete", "patch", "head" ], "example": "get" }, "data": { "description": "For `GET` requests, this should be a map of query parameters you would have normally passed in the URL. Options and pagination are not accepted here; put them in `options` instead. For `POST`, `PATCH`, and `PUT` methods, this should be the content you would have normally put in the data field of the body.", "type": "object", "example": { "assignee": "me", "workspace": "1337" } }, "options": { "description": "Pagination (`limit` and `offset`) and output options (`fields` or `expand`) for the action. \u201cPretty\u201d JSON output is not an available option on individual actions; if you want pretty output, specify that option on the parent request.", "type": "object", "properties": { "limit": { "description": "Pagination limit for the request.", "type": "integer", "example": 50 }, "offset": { "description": "Pagination offset for the request.", "type": "integer", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "fields": { "description": "The fields to retrieve in the request.", "type": "array", "items": { "type": "string" }, "example": [ "name", "gid", "notes", "completed" ] } }, "example": { "limit": 3, "fields": [ "name", "notes", "completed" ] } } }, "required": [ "relative_path", "method" ] }, "BatchResponse": { "description": "A response object returned from a batch request.", "type": "object", "properties": { "status_code": { "description": "The HTTP status code that the invoked endpoint returned.", "type": "integer", "example": 200 }, "headers": { "description": "A map of HTTP headers specific to this result. This is primarily used for returning a `Location` header to accompany a `201 Created` result. The parent HTTP response will contain all common headers.", "type": "object", "example": { "location": "/tasks/1234" } }, "body": { "description": "The JSON body that the invoked endpoint returned.", "type": "object", "example": { "data": { "gid": "1967", "completed": false, "name": "Hello, world!", "notes": "How are you today?" } } } } }, "CustomFieldBase": { "allOf": [ { "$ref": "#/components/schemas/CustomFieldCompact" }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "$ref": "#/components/schemas/EnumOption" } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, "CustomFieldCompact": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "$ref": "#/components/schemas/EnumOption" } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "$ref": "#/components/schemas/EnumOption" }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "$ref": "#/components/schemas/EnumOption" } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, "CustomFieldRequest": { "allOf": [ { "$ref": "#/components/schemas/CustomFieldBase" }, { "type": "object", "required": [ "workspace" ], "properties": { "workspace": { "type": "string", "description": "*Create-Only* The workspace to create a custom field in.", "example": "1331" }, "owned_by_app": { "type": "boolean", "description": "*Allow-listed*. Instructs the API that this Custom Field is app-owned. This parameter is allow-listed to specific apps at this point in time. For apps that are not allow-listed, providing this parameter will result in a `403 Forbidden`." }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of user GIDs reflects the users to be written to a `people` custom field. Note that *write* operations will replace existing users (if any) in the custom field with the users specified in this array.", "type": "array", "items": { "type": "string", "description": "The GID of a user." }, "example": [ "12345" ] }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of GIDs reflects the objects to be written to a `reference` custom field. Note that *write* operations will replace existing objects (if any) in the custom field with the objects specified in this array.", "type": "array", "items": { "type": "string", "description": "The GID of an object." }, "example": [ "12345" ] } } } ] }, "CustomFieldCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/CustomFieldRequest" }, { "type": "object", "required": [ "resource_subtype" ], "properties": { "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.", "type": "string", "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, "CustomFieldResponse": { "allOf": [ { "$ref": "#/components/schemas/CustomFieldBase" }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/UserCompact" }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "$ref": "#/components/schemas/UserCompact" } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "$ref": "#/components/schemas/AsanaNamedResource" } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, "CustomFieldSettingBase": { "$ref": "#/components/schemas/CustomFieldSettingCompact" }, "CustomFieldSettingCompact": { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, "CustomFieldSettingResponse": { "allOf": [ { "$ref": "#/components/schemas/CustomFieldSettingBase" }, { "type": "object", "properties": { "project": { "allOf": [ { "$ref": "#/components/schemas/ProjectCompact" }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "$ref": "#/components/schemas/ProjectCompact" }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "$ref": "#/components/schemas/CustomFieldResponse" }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] }, "CustomTypeBase": { "$ref": "#/components/schemas/CustomTypeCompact" }, "CustomTypeCompact": { "description": "Custom Types extend the types of Asana Objects, currently only Custom Tasks are supported.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type.", "example": "Bug ticket" } } }, "CustomTypeResponse": { "allOf": [ { "$ref": "#/components/schemas/CustomTypeBase" }, { "type": "object", "properties": { "status_options": { "type": "array", "nullable": true, "description": "The available options for the custom type.", "items": { "$ref": "#/components/schemas/CustomTypeStatusOptionResponse" } } } } ] }, "CustomTypeStatusOptionBase": { "$ref": "#/components/schemas/CustomTypeStatusOptionCompact" }, "CustomTypeStatusOptionCompact": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type_status_option", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type status option.", "example": "Solution pending" } } }, "CustomTypeStatusOptionResponse": { "allOf": [ { "$ref": "#/components/schemas/CustomTypeStatusOptionBase" }, { "type": "object", "properties": { "completion_state": { "description": "The completion state the custom type status option corresponds to, all custom types must have one \u2018Incomplete\u2019 and \u2018Complete\u2019 status option.", "type": "string", "example": "Incomplete", "nullable": true }, "enabled": { "description": "Whether or not the custom type status option is a selectable value for the custom type.", "type": "boolean", "example": true, "nullable": true }, "color": { "description": "The color associated with the custom type status option. Defaults to \u2018none\u2019.", "type": "string", "example": "blue", "nullable": true } } } ] }, "EmptyResponse": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." }, "EnumOption": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "EnumOptionBase": { "$ref": "#/components/schemas/EnumOption" }, "EnumOptionInsertRequest": { "type": "object", "required": [ "enum_option" ], "properties": { "enum_option": { "type": "string", "description": "The gid of the enum option to relocate.", "example": "97285" }, "before_enum_option": { "type": "string", "description": "An existing enum option within this custom field before which the new enum option should be inserted. Cannot be provided together with after_enum_option.", "example": "12345" }, "after_enum_option": { "type": "string", "description": "An existing enum option within this custom field after which the new enum option should be inserted. Cannot be provided together with before_enum_option.", "example": "12345" } } }, "EnumOptionRequest": { "allOf": [ { "$ref": "#/components/schemas/EnumOptionBase" }, { "type": "object", "properties": { "insert_before": { "type": "string", "description": "An existing enum option within this custom field before which the new enum option should be inserted. Cannot be provided together with after_enum_option.", "example": "12345" }, "insert_after": { "type": "string", "description": "An existing enum option within this custom field after which the new enum option should be inserted. Cannot be provided together with before_enum_option.", "example": "12345" } } } ] }, "Error": { "type": "object", "properties": { "message": { "type": "string", "readOnly": true, "description": "Message providing more detail about the error that occurred, if available.", "example": "project: Missing input" }, "help": { "type": "string", "readOnly": true, "description": "Additional information directing developers to resources on how to address and fix the problem, if available.", "example": "For more information on API status codes and how to handle them, read the docs on errors: https://asana.github.io/developer-docs/#errors'" }, "phrase": { "type": "string", "readOnly": true, "description": "*500 errors only*. A unique error phrase which can be used when contacting developer support to help identify the exact occurrence of the problem in Asana's logs.", "example": "6 sad squid snuggle softly" } } }, "ErrorResponse": { "description": "Sadly, sometimes requests to the API are not successful. Failures can\noccur for a wide range of reasons. In all cases, the API should return\nan HTTP Status Code that indicates the nature of the failure,\nwith a response body in JSON format containing additional information.\n\n\nIn the event of a server error the response body will contain an error\nphrase. These phrases are automatically generated using the\n[node-asana-phrase\nlibrary](https://github.com/Asana/node-asana-phrase) and can be used by\nAsana support to quickly look up the incident that caused the server\nerror.", "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "EventResponse": { "description": "An *event* is an object representing a change to a resource that was\nobserved by an event subscription or delivered asynchronously to\nthe target location of an active webhook.\n\nThe event may be triggered by a different `user` than the\nsubscriber. For example, if user A subscribes to a task and user B\nmodified it, the event's user will be user B. Note: Some events\nare generated by the system, and will have `null` as the user. API\nconsumers should make sure to handle this case.\n\nThe `resource` that triggered the event may be different from the one\nthat the events were requested for or the webhook is subscribed to. For\nexample, a subscription to a project will contain events for tasks\ncontained within the project.\n\n**Note:** pay close attention to the relationship between the fields\n`Event.action` and `Event.change.action`.\n`Event.action` represents the action taken on the resource\nitself, and `Event.change.action` represents how the information\nwithin the resource's fields have been modified.\n\nFor instance, consider these scenarios:\n\n\n* When at task is added to a project, `Event.action` will be\n`added`, `Event.parent` will be an object with the `id` and\n`type` of the project, and there will be no `change` field.\n\n\n* When an assignee is set on the task, `Event.parent` will be\n`null`, `Event.action` will be `changed`,\n`Event.change.action` will be `changed`, and `new_value` will\nbe an object with the user's `id` and `type`.\n\n\n* When a collaborator is added to the task, `Event.parent` will\nbe `null`, `Event.action` will be `changed`,\n`Event.change.action` will be `added`, and `added_value` will be\nan object with the user's `id` and `type`.", "type": "object", "properties": { "user": { "allOf": [ { "$ref": "#/components/schemas/UserCompact" }, { "description": "The user who triggered the event." } ] }, "resource": { "allOf": [ { "$ref": "#/components/schemas/AsanaNamedResource" }, { "description": "The resource which has triggered the event by being modified in some way." } ] }, "type": { "description": "*Deprecated: Refer to the resource_type of the resource.* The type of the resource that generated the event.", "type": "string", "readOnly": true, "example": "task" }, "action": { "description": "The type of action taken on the **resource** that triggered the event. This can be one of `changed`, `added`, `removed`, `deleted`, or `undeleted` depending on the nature of the event.", "type": "string", "readOnly": true, "example": "changed" }, "parent": { "allOf": [ { "$ref": "#/components/schemas/AsanaNamedResource" }, { "description": "For added/removed events, the parent object that resource was added to or removed from. The parent will be `null` for other event types." } ] }, "created_at": { "description": "The timestamp when the event occurred.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "change": { "type": "object", "description": "Information about the type of change that has occurred. This field is only present when the value of the property `action`, describing the action taken on the **resource**, is `changed`.", "readOnly": true, "properties": { "field": { "description": "The name of the field that has changed in the resource.", "type": "string", "readOnly": true, "example": "assignee" }, "action": { "description": "The type of action taken on the **field** which has been changed. This can be one of `changed`, `added`, or `removed` depending on the nature of the change.", "type": "string", "readOnly": true, "example": "changed" }, "new_value": { "description": "*Conditional.* This property is only present when the value of the event's `change.action` is `changed` _and_ the `new_value` is an Asana resource. This will be only the `gid` and `resource_type` of the resource when the events come from webhooks; this will be the compact representation (and can have fields expanded with [opt_fields](/docs/inputoutput-options)) when using the [get events](/reference/getevents) endpoint.", "example": { "gid": "12345", "resource_type": "user" } }, "added_value": { "description": "*Conditional.* This property is only present when the value of the event's `change.action` is `added` _and_ the `added_value` is an Asana resource. This will be only the `gid` and `resource_type` of the resource when the events come from webhooks; this will be the compact representation (and can have fields expanded with [opt_fields](/docs/inputoutput-options)) when using the [get events](/reference/getevents) endpoint.", "example": { "gid": "12345", "resource_type": "user" } }, "removed_value": { "description": "*Conditional.* This property is only present when the value of the event's `change.action` is `removed` _and_ the `removed_value` is an Asana resource. This will be only the `gid` and `resource_type` of the resource when the events come from webhooks; this will be the compact representation (and can have fields expanded with [opt_fields](/docs/inputoutput-options)) when using the [get events](/reference/getevents) endpoint.", "example": { "gid": "12345", "resource_type": "user" } } } } } }, "GoalAddSubgoalRequest": { "type": "object", "required": [ "subgoal" ], "properties": { "subgoal": { "description": "The goal gid to add as subgoal to a parent goal", "type": "string", "example": "1331" }, "insert_before": { "description": "An id of a subgoal of this parent goal. The new subgoal will be added before the one specified here. `insert_before` and `insert_after` parameters cannot both be specified.", "type": "string", "example": "1331" }, "insert_after": { "description": "An id of a subgoal of this parent goal. The new subgoal will be added after the one specified here. `insert_before` and `insert_after` parameters cannot both be specified.", "type": "string", "example": "1331" } } }, "GoalAddSupportingWorkRequest": { "type": "object", "required": [ "supporting_work" ], "properties": { "supporting_work": { "description": "The project/task/portfolio gid to add as supporting work for a goal", "type": "string", "example": "1331" } } }, "GoalBase": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "html_notes": { "type": "string", "description": "The notes of the goal with formatting as HTML.", "example": "Start building brand awareness." }, "notes": { "type": "string", "description": "Free-form textual information associated with the goal (i.e. its description).", "example": "Start building brand awareness." }, "due_on": { "type": "string", "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "example": "2019-09-15", "nullable": true }, "start_on": { "type": "string", "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "example": "2019-09-14", "nullable": true }, "is_workspace_level": { "type": "boolean", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization. Whether the goal belongs to the `workspace` (and is listed as part of the workspace\u2019s goals) or not. If it isn\u2019t a workspace-level goal, it is a team-level goal, and is associated with the goal\u2019s team.", "example": true }, "liked": { "type": "boolean", "description": "True if the goal is liked by the authorized user, false if not.", "example": false } } }, "GoalCompact": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "$ref": "#/components/schemas/UserCompact" }, { "type": "object", "nullable": true } ] } } }, "GoalMetricBase": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "number", "enum": [ "number" ] }, "precision": { "description": "*Conditional*. Only relevant for goal metrics of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.", "type": "integer", "example": 2 }, "unit": { "description": "A supported unit of measure for the goal metric, or none.", "type": "string", "enum": [ "none", "currency", "percentage" ] }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "initial_number_value": { "description": "This number is the start value of a goal metric of type number.", "type": "number", "example": 5.2 }, "target_number_value": { "description": "This number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`.", "type": "number", "example": 10.2 }, "current_number_value": { "description": "This number is the current value of a goal metric of type number.", "type": "number", "example": 8.12 }, "current_display_value": { "description": "This string is the current value of a goal metric of type string.", "type": "string", "readOnly": true, "example": "8.12" }, "progress_source": { "description": "This field defines how the progress value of a goal metric is being calculated. A goal's progress can be provided manually by the user, calculated automatically from contributing subgoals, projects, or tasks, or managed by an integration with an external data source, such as Salesforce.", "type": "string", "enum": [ "manual", "subgoal_progress", "project_task_completion", "project_milestone_completion", "task_completion", "external" ], "example": "manual" }, "is_custom_weight": { "description": "*Conditional*. Only relevant if `metric.progress_source` is one of `subgoal_progress`, `project_task_completion`, `project_milestone_completion`, or `task_completion`. If true, we use the supporting object's custom weight to calculate the goal's progress. If false, we treat all supporting objects as equally weighted", "type": "boolean", "example": false } } }, "GoalRemoveSupportingRelationshipRequest": { "type": "object", "required": [ "supporting_resource" ], "properties": { "supporting_resource": { "description": "The gid of the supporting resource to remove from the parent goal. Must be the gid of a goal, project, task, or portfolio.", "type": "string", "example": "12345" } } }, "GoalAddSupportingRelationshipRequest": { "type": "object", "required": [ "supporting_resource" ], "properties": { "supporting_resource": { "description": "The gid of the supporting resource to add to the parent goal. Must be the gid of a goal, project, task, or portfolio.", "type": "string", "example": "12345" }, "insert_before": { "description": "An id of a subgoal of this parent goal. The new subgoal will be added before the one specified here. `insert_before` and `insert_after` parameters cannot both be specified. Currently only supported when adding a subgoal.", "type": "string", "example": "1331" }, "insert_after": { "description": "An id of a subgoal of this parent goal. The new subgoal will be added after the one specified here. `insert_before` and `insert_after` parameters cannot both be specified. Currently only supported when adding a subgoal.", "type": "string", "example": "1331" }, "contribution_weight": { "description": "Defines how much the supporting goal\u2019s progress contributes to the parent goal\u2019s overall progress. When used with automatically calculated [Goal Metrics](/reference/creategoalmetric) (such as `progress_source = subgoal_progress`), this value must be greater than 0 for the subgoal to count toward the parent goal\u2019s progress.\nAccepts a number between 0 and 1 (inclusive). Defaults to `0`.", "type": "number", "example": 0 } } }, "GoalMetricCurrentValueRequest": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "current_number_value": { "description": "*Conditional*. This number is the current value of a goal metric of type number.", "type": "number", "example": 8.12 } } }, "GoalMetricRequest": { "$ref": "#/components/schemas/GoalMetricBase" }, "GoalRemoveSubgoalRequest": { "type": "object", "required": [ "subgoal" ], "properties": { "subgoal": { "description": "The goal gid to remove as subgoal from the parent goal", "type": "string", "example": "1331" } } }, "GoalRequestBase": { "allOf": [ { "$ref": "#/components/schemas/GoalBase" }, { "type": "object", "properties": { "team": { "type": "string", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization.", "example": "12345", "nullable": true }, "workspace": { "type": "string", "description": "The `gid` of a workspace.", "example": "12345" }, "time_period": { "type": "string", "description": "The `gid` of a time period.", "example": "12345", "nullable": true }, "owner": { "type": "string", "description": "The `gid` of a user.", "example": "12345", "nullable": true } } } ] }, "GoalRequest": { "allOf": [ { "$ref": "#/components/schemas/GoalRequestBase" }, { "type": "object", "properties": { "followers": { "type": "array", "items": { "type": "string", "description": "The `gid` of a user." }, "example": [ "12345" ] } } } ] }, "GoalUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/GoalRequestBase" }, { "type": "object", "properties": { "status": { "type": "string", "description": "The current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect \"On Track\", \"At Risk\", and \"Off Track\", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.\n*Note* you can only write to this property if `metric` is set.", "example": "green", "nullable": true } } } ] }, "GoalResponse": { "allOf": [ { "$ref": "#/components/schemas/GoalBase" }, { "type": "object", "properties": { "likes": { "description": "Array of likes for users who have liked this goal.", "type": "array", "items": { "$ref": "#/components/schemas/Like" }, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this goal.", "type": "integer", "readOnly": true, "example": 5 }, "team": { "allOf": [ { "$ref": "#/components/schemas/TeamCompact" }, { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when the `workspace` provided is an organization." } ] }, "workspace": { "allOf": [ { "$ref": "#/components/schemas/WorkspaceCompact" }, { "type": "object" } ] }, "followers": { "type": "array", "items": { "$ref": "#/components/schemas/UserCompact" }, "description": "Array of users who are members of this goal." }, "time_period": { "allOf": [ { "$ref": "#/components/schemas/TimePeriodCompact" }, { "type": "object", "nullable": true } ] }, "metric": { "allOf": [ { "$ref": "#/components/schemas/GoalMetricBase" }, { "type": "object", "nullable": true, "properties": { "can_manage": { "description": "*Conditional*. Only relevant for `progress_source` of type `external`. This boolean indicates whether the requester has the ability to update the current value of this metric. This returns `true` if the external metric was created by the requester, `false` otherwise.", "type": "boolean", "readOnly": true, "example": true } } } ] }, "owner": { "allOf": [ { "$ref": "#/components/schemas/UserCompact" }, { "type": "object", "nullable": true } ] }, "current_status_update": { "allOf": [ { "$ref": "#/components/schemas/StatusUpdateCompact" }, { "description": "The latest `status_update` posted to this goal.", "nullable": true } ] }, "status": { "type": "string", "readOnly": true, "description": "The current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect \"On Track\", \"At Risk\", and \"Off Track\", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.\n*Note* you can only write to this property if `metric` is set.", "example": "green", "nullable": true } } } ] }, "GoalRelationshipBase": { "allOf": [ { "$ref": "#/components/schemas/GoalRelationshipCompact" }, { "type": "object", "properties": { "supported_goal": { "allOf": [ { "$ref": "#/components/schemas/GoalCompact" }, { "type": "object", "readOnly": true, "description": "The goal that the supporting resource supports." } ] } } } ] }, "GoalRelationshipCompact": { "description": "A *goal relationship* is an object representing the relationship between a goal and another goal, a project, a task, or a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal_relationship", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "subgoal", "enum": [ "subgoal", "supporting_work" ] }, "supporting_resource": { "allOf": [ { "$ref": "#/components/schemas/ProjectCompact" }, { "type": "object", "readOnly": true, "description": "The supporting resource that supports the goal. This can be either a project, task, portfolio, or goal." } ] }, "contribution_weight": { "description": "The weight that the supporting resource's progress contributes to the supported goal's progress. This can be 0, 1, or any value in between.", "type": "number", "example": 1.0 } } }, "GoalRelationshipRequest": { "allOf": [ { "$ref": "#/components/schemas/GoalRelationshipBase" }, { "type": "object" } ] }, "GoalRelationshipResponse": { "allOf": [ { "$ref": "#/components/schemas/GoalRelationshipBase" }, { "type": "object" } ] }, "JobBase": { "$ref": "#/components/schemas/JobCompact" }, "JobCompact": { "description": "A *job* is an object representing a process that handles asynchronous work.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "job", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "duplicate_task" }, "status": { "description": "The current status of this job.", "type": "string", "enum": [ "not_started", "in_progress", "succeeded", "failed" ], "readOnly": true, "example": "in_progress" }, "new_project": { "$ref": "#/components/schemas/ProjectCompact" }, "new_task": { "allOf": [ { "$ref": "#/components/schemas/TaskCompact" }, { "type": "object", "nullable": true } ] }, "new_project_template": { "$ref": "#/components/schemas/ProjectTemplateCompact" }, "new_graph_export": { "$ref": "#/components/schemas/GraphExportCompact" }, "new_resource_export": { "$ref": "#/components/schemas/ResourceExportCompact" } } }, "JobResponse": { "$ref": "#/components/schemas/JobBase" }, "Like": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "$ref": "#/components/schemas/UserCompact" } } }, "MemberCompact": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "MembershipCompact": { "anyOf": [ { "$ref": "#/components/schemas/GoalMembershipCompact" }, { "$ref": "#/components/schemas/ProjectMembershipCompactResponse" }, { "$ref": "#/components/schemas/PortfolioMembershipCompactResponse" }, { "$ref": "#/components/schemas/CustomFieldMembershipCompact" } ] }, "ModifyDependenciesRequest": { "type": "object", "properties": { "dependencies": { "description": "An array of task gids that a task depends on.", "type": "array", "items": { "type": "string" } } }, "example": { "dependencies": [ "133713", "184253" ] } }, "ModifyDependentsRequest": { "description": "A set of dependent tasks.", "type": "object", "properties": { "dependents": { "description": "An array of task gids that are dependents of the given task.", "type": "array", "items": { "type": "string" } } }, "example": { "dependents": [ "133713", "184253" ] } }, "NextPage": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } }, "OrganizationExportBase": { "$ref": "#/components/schemas/OrganizationExportCompact" }, "OrganizationExportCompact": { "description": "An *organization_export* object represents a request to export the complete data of an Organization in JSON format.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "organization_export", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export of the organization\nin JSON format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or\nfailed. If present, this URL may only be valid for 1 hour from\nthe time of retrieval. You should avoid persisting this URL\nsomewhere and rather refresh on demand to ensure you do not keep\nstale URLs.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/domain_export/7588024658887731/download/ domain_export_2563645399633793_7588024658887731_2023018-201726.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Content-Sha256=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host&x-id=GetObject#_=_" }, "state": { "description": "The current state of the export.", "type": "string", "enum": [ "pending", "started", "finished", "error" ], "readOnly": true, "example": "started" }, "organization": { "$ref": "#/components/schemas/WorkspaceCompact" } } }, "OrganizationExportRequest": { "type": "object", "description": "An *organization_export* request starts a job to export the complete data of the given Organization.", "properties": { "organization": { "description": "Globally unique identifier for the workspace or organization.", "type": "string", "example": "1331" } } }, "OrganizationExportResponse": { "$ref": "#/components/schemas/OrganizationExportBase" }, "PortfolioAddItemRequest": { "type": "object", "required": [ "item" ], "properties": { "item": { "description": "The item to add to the portfolio.", "type": "string", "example": "1331" }, "insert_before": { "description": "An id of an item in this portfolio. The new item will be added before the one specified here. `insert_before` and `insert_after` parameters cannot both be specified.", "type": "string", "example": "1331" }, "insert_after": { "description": "An id of an item in this portfolio. The new item will be added after the one specified here. `insert_before` and `insert_after` parameters cannot both be specified.", "type": "string", "example": "1331" } } }, "PortfolioBase": { "allOf": [ { "$ref": "#/components/schemas/PortfolioCompact" }, { "type": "object", "properties": { "archived": { "description": "[Opt In](/docs/inputoutput-options). True if the portfolio is archived, false if not. Archived portfolios do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the portfolio.", "type": "string", "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray" ], "example": "light-green" }, "start_on": { "description": "The day on which work for this portfolio begins, or null if the portfolio has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "due_on": { "description": "The day on which this portfolio is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "default_access_level": { "description": "The default access level when inviting new members to the portfolio", "type": "string", "enum": [ "admin", "editor", "viewer" ], "example": "viewer" } } } ] }, "PortfolioCompact": { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, "PortfolioMembershipBase": { "$ref": "#/components/schemas/PortfolioMembershipCompact" }, "DeprecatedPortfolioMembershipBase": { "$ref": "#/components/schemas/DeprecatedPortfolioMembershipCompact" }, "DeprecatedPortfolioMembershipResponse": { "$ref": "#/components/schemas/DeprecatedPortfolioMembershipBase" }, "DeprecatedPortfolioMembershipCompact": { "description": "This object determines if a user is a member of a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio_membership", "x-insert-after": "gid" }, "portfolio": { "description": "[Opt In](/docs/inputoutput-options). The portfolio the user is a member of.", "$ref": "#/components/schemas/PortfolioCompact" }, "user": { "$ref": "#/components/schemas/UserCompact" }, "access_level": { "description": "Whether the member has admin, editor, or viewer access to the portfolio. Portfolios do not support commenter access yet.", "type": "string", "enum": [ "admin", "editor", "viewer" ], "readOnly": true, "example": "admin" } } }, "PortfolioMembershipCompact": { "description": "This object determines if a user is a member of a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio_membership", "x-insert-after": "gid" }, "parent": { "description": "The portfolio the user is a member of.", "$ref": "#/components/schemas/PortfolioCompact" }, "member": { "description": "Member can be a user or a team.", "$ref": "#/components/schemas/MemberCompact" }, "access_level": { "description": "Whether the member has admin, editor, or viewer access to the portfolio. Portfolios do not support commenter access yet.", "type": "string", "enum": [ "admin", "editor", "viewer" ], "readOnly": true, "example": "admin" } } }, "PortfolioMembershipCompactResponse": { "allOf": [ { "$ref": "#/components/schemas/PortfolioMembershipCompact" }, { "type": "object", "properties": { "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "membership" }, "resource_subtype": { "description": "Type of the membership.", "type": "string", "example": "portfolio_membership" } } } ] }, "PortfolioMembershipResponse": { "$ref": "#/components/schemas/PortfolioMembershipBase" }, "PortfolioRemoveItemRequest": { "type": "object", "required": [ "item" ], "properties": { "item": { "description": "The item to remove from the portfolio.", "type": "string", "example": "1331" } } }, "PortfolioRequest": { "allOf": [ { "$ref": "#/components/schemas/PortfolioBase" }, { "type": "object", "properties": { "workspace": { "type": "string", "description": "*Create-only*. The workspace or organization that the portfolio belongs to.", "example": "167589" }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false } } } ] }, "PortfolioUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/PortfolioBase" }, { "type": "object", "properties": { "custom_fields": { "description": "An object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, or object (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.", "type": "object", "additionalProperties": { "type": "string", "description": "\"{custom_field_gid}\" => Value (can be text, enum GID, a number, etc.). For date, use format \"YYYY-MM-DD\" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z)." }, "example": { "5678904321": "On Hold", "4578152156": "Not Started" } } } } ] }, "PortfolioResponse": { "allOf": [ { "$ref": "#/components/schemas/PortfolioBase" }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "$ref": "#/components/schemas/UserCompact" }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of custom field settings applied to the portfolio.", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldSettingResponse" } }, "current_status_update": { "allOf": [ { "$ref": "#/components/schemas/StatusUpdateCompact" }, { "description": "The latest `status_update` posted to this portfolio.", "nullable": true } ] }, "custom_fields": { "description": "Array of Custom Fields.", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldCompact" } }, "members": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/UserCompact" } }, "owner": { "$ref": "#/components/schemas/UserCompact" }, "workspace": { "allOf": [ { "$ref": "#/components/schemas/WorkspaceCompact" }, { "type": "object", "description": "*Create-only*. The workspace or organization that the portfolio belongs to." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" }, "public": { "description": "True if the portfolio is public to its workspace members.", "type": "boolean", "example": false }, "privacy_setting": { "description": "The privacy setting of the portfolio. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_domain", "members_only" ], "example": "members_only" }, "project_templates": { "description": "Array of project templates that are in the portfolio", "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/ProjectTemplateCompact" } } } } ] }, "Preview": { "type": "object", "description": "A collection of rich text that will be displayed as a preview to another app.\n\nThis is read-only except for a small group of whitelisted apps.", "readOnly": true, "properties": { "fallback": { "description": "Some fallback text to display if unable to display the full preview.", "type": "string", "example": "Greg: Great! I like this idea.\\n\\nhttps//a_company.slack.com/archives/ABCDEFG/12345678" }, "footer": { "description": "Text to display in the footer.", "type": "string", "example": "Mar 17, 2019 1:25 PM" }, "header": { "description": "Text to display in the header.", "type": "string", "example": "Asana for Slack" }, "header_link": { "description": "Where the header will link to.", "type": "string", "example": "https://asana.comn/apps/slack" }, "html_text": { "description": "HTML formatted text for the body of the preview.", "type": "string", "example": "Great! I like this idea." }, "text": { "description": "Text for the body of the preview.", "type": "string", "example": "Great! I like this idea." }, "title": { "description": "Text to display as the title.", "type": "string", "example": "Greg" }, "title_link": { "description": "Where to title will link to.", "type": "string", "example": "https://asana.slack.com/archives/ABCDEFG/12345678" } } }, "ProjectBase": { "allOf": [ { "$ref": "#/components/schemas/ProjectCompact" }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "$ref": "#/components/schemas/ProjectStatusResponse" }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "$ref": "#/components/schemas/StatusUpdateCompact" }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldSettingResponse" } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "$ref": "#/components/schemas/UserCompact" }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, "ProjectBriefBase": { "allOf": [ { "$ref": "#/components/schemas/ProjectBriefCompact" }, { "type": "object", "properties": { "title": { "description": "The title of the project brief.", "type": "string", "example": "Stuff to buy \u2014 Project Brief" }, "html_text": { "description": "HTML formatted text for the project brief.", "type": "string", "example": "This is a project brief." } } } ] }, "ProjectBriefCompact": { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, "ProjectBriefRequest": { "allOf": [ { "$ref": "#/components/schemas/ProjectBriefBase" }, { "type": "object", "properties": { "text": { "description": "The plain text of the project brief. When writing to a project brief, you can specify either `html_text` (preferred) or `text`, but not both.", "type": "string", "example": "This is a project brief." } } } ] }, "ProjectBriefResponse": { "allOf": [ { "$ref": "#/components/schemas/ProjectBriefBase" }, { "type": "object", "properties": { "text": { "description": "[Opt In](/docs/inputoutput-options). The plain text of the project brief.", "type": "string", "example": "This is a project brief." }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/11111111/22222222" }, "project": { "allOf": [ { "$ref": "#/components/schemas/ProjectCompact" }, { "type": "object", "description": "The project with which this project brief is associated." } ] } } } ] }, "ProjectCompact": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "ProjectDuplicateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "description": "The name of the new project.", "type": "string", "example": "New Project Name" }, "team": { "description": "Sets the team of the new project. If team is not defined, the new project will be in the same team as the the original project.", "type": "string", "example": "12345" }, "include": { "description": "A comma-separated list of elements to include when duplicating a project.\nSome elements are automatically included and cannot be excluded,\nwhile others are **optional** and must be explicitly specified in this field.\n\n**Auto-included fields (non-configurable)**\n- Tasks\n- [Project Views](https://asana.com/features/project-management/project-views)\n(i.e., tabs in a project such as List, Board, Dashboard, etc.)\n- [Rules](https://help.asana.com/s/article/rules)\n\n*Note: The Owner of the Rules copied to the new project is the user who performs the API call.\nIf the duplication is performed using a [Service Account](/docs/authentication#/service-account),\nnote that Service Accounts cannot access the UI to modify or pause Rules.\nTo prevent unwanted automation behavior, consider pausing Rules in the source project before duplication \u2014\ntheir active/paused state is preserved in the new project.*\n\n**Optional fields (configurable)**\n- allocations\n- forms\n- members\n- notes\n- permissions\n- task_assignee\n- task_attachments\n- task_dates\n- task_dependencies\n- task_followers\n- task_notes\n- task_projects\n- task_subtasks\n- task_tags\n- task_templates\n- task_type_default", "type": "string", "pattern": "([allocations|forms|members|notes|permissions|task_assignee|task_attachments|task_dates|task_dependencies|task_followers|task_notes|task_projects|task_subtasks|task_tags|task_templates|task_type_default])(,\\1)*", "example": [ "allocations,forms,members,notes,permissions,task_assignee,task_attachments,task_dates,task_dependencies,task_followers,task_notes,task_projects,task_subtasks,task_tags,task_templates,task_type_default" ] }, "schedule_dates": { "description": "A dictionary of options to auto-shift dates. `task_dates` must be included to use this option. Requires `should_skip_weekends` and either `start_on` or `due_on`, but not both.", "type": "object", "properties": { "should_skip_weekends": { "description": "**Required**: Determines if the auto-shifted dates should skip weekends.", "type": "boolean", "example": true }, "due_on": { "description": "Sets the last due date in the duplicated project to the given date. The rest of the due dates will be offset by the same amount as the due dates in the original project.", "type": "string", "example": "2019-05-21" }, "start_on": { "description": "Sets the first start date in the duplicated project to the given date. The rest of the start dates will be offset by the same amount as the start dates in the original project.", "type": "string", "example": "2019-05-21" } } } } }, "CustomFieldMembershipBase": { "$ref": "#/components/schemas/CustomFieldMembershipCompact" }, "CustomFieldMembershipCompact": { "description": "This object describes a user or team's membership to a custom field including their level of access (Admin, Editor, or User).", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_membership", "x-insert-after": "gid" }, "resource_subtype": { "description": "Type of the membership.", "type": "string", "example": "custom_field_membership" }, "parent": { "description": "The custom field the user or team is a member of.", "$ref": "#/components/schemas/CustomFieldCompact" }, "member": { "description": "Member can be a user or a team.", "$ref": "#/components/schemas/MemberCompact" }, "access_level": { "description": "Whether the member has admin, editor, or user access to the custom field.", "type": "string", "enum": [ "admin", "editor", "user" ], "readOnly": true, "example": "admin" } } }, "CustomFieldMembershipResponse": { "$ref": "#/components/schemas/CustomFieldMembershipBase" }, "ProjectMembershipBase": { "$ref": "#/components/schemas/ProjectMembershipCompact" }, "ProjectMembershipCompact": { "description": "This object describes a team or a user's membership to a project including their level of access (Admin, Editor, Commenter, or Viewer).", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_membership", "x-insert-after": "gid" }, "parent": { "description": "[Opt In](/docs/inputoutput-options). The project the user is a member of.", "$ref": "#/components/schemas/ProjectCompact" }, "member": { "description": "Member can be a user or a team.", "$ref": "#/components/schemas/MemberCompact" }, "access_level": { "description": "Whether the member has admin, editor, commenter, or viewer access to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "readOnly": true, "example": "admin" } } }, "ProjectMembershipCompactResponse": { "allOf": [ { "$ref": "#/components/schemas/ProjectMembershipCompact" }, { "type": "object", "properties": { "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "membership" }, "resource_subtype": { "description": "Type of the membership.", "type": "string", "example": "project_membership" } } } ] }, "ProjectMembershipNormalResponse": { "allOf": [ { "$ref": "#/components/schemas/ProjectMembershipBase" }, { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/UserCompact" }, "project": { "description": "[Opt In](/docs/inputoutput-options). The project the user is a member of.", "$ref": "#/components/schemas/ProjectCompact" }, "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "project_membership" }, "write_access": { "description": "Whether the member has full access or comment-only access to the project.", "type": "string", "enum": [ "full_write", "comment_only" ], "readOnly": true, "example": "full_write" } } } ] }, "ProjectRequest": { "allOf": [ { "$ref": "#/components/schemas/ProjectBase" }, { "type": "object", "properties": { "custom_fields": { "description": "An object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, or object (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.", "type": "object", "additionalProperties": { "type": "string", "description": "\"{custom_field_gid}\" => Value (can be text, a number, etc.). For date, use format \"YYYY-MM-DD\" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z)." }, "example": { "5678904321": "On Hold", "4578152156": "Not Started" } }, "followers": { "description": "*Create-only*. Comma separated string of users. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "string", "example": "12345,23456" }, "owner": { "description": "The current owner of the project, may be null.", "nullable": true, "type": "string", "example": "12345" }, "team": { "description": "The team that this project is shared with.", "type": "string", "example": "12345" }, "workspace": { "type": "string", "description": "The `gid` of a workspace.", "example": "12345" } } } ] }, "ProjectUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/ProjectBase" }, { "type": "object", "properties": { "custom_fields": { "description": "An object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, or object (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.", "type": "object", "additionalProperties": { "type": "string", "description": "\"{custom_field_gid}\" => Value (can be text, a number, etc.). For date, use format \"YYYY-MM-DD\" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z)." }, "example": { "5678904321": "On Hold", "4578152156": "Not Started" } }, "followers": { "description": "*Create-only*. Comma separated string of users. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "string", "example": "12345,23456" }, "owner": { "description": "The current owner of the project, may be null.", "nullable": true, "type": "string", "example": "12345" }, "team": { "description": "The team that this project is shared with.", "type": "string", "example": "12345" } } } ] }, "ProjectResponse": { "allOf": [ { "$ref": "#/components/schemas/ProjectBase" }, { "type": "object", "properties": { "custom_fields": { "description": "Array of Custom Fields.", "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldCompact" } }, "completed": { "description": "True if the project is currently marked complete, false if not.", "type": "boolean", "readOnly": true, "example": false }, "completed_at": { "description": "The time at which this project was completed, or null if the project is not completed.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "$ref": "#/components/schemas/UserCompact" }, { "description": "The user that marked this project complete, or null if the project is not completed.", "readOnly": true, "nullable": true } ] }, "followers": { "description": "Array of users following this project. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "array", "items": { "$ref": "#/components/schemas/UserCompact" }, "readOnly": true }, "owner": { "description": "The current owner of the project, may be null.", "allOf": [ { "$ref": "#/components/schemas/UserCompact" }, { "type": "object", "nullable": true } ] }, "team": { "allOf": [ { "$ref": "#/components/schemas/TeamCompact" }, { "type": "object", "description": "The team that this project is shared with." } ] }, "icon": { "description": "The icon for a project.", "type": "string", "nullable": true, "enum": [ "list", "board", "timeline", "calendar", "rocket", "people", "graph", "star", "bug", "light_bulb", "globe", "gear", "notebook", "computer", "check", "target", "html", "megaphone", "chat_bubbles", "briefcase", "page_layout", "mountain_flag", "puzzle", "presentation", "line_and_symbols", "speed_dial", "ribbon", "shoe", "shopping_basket", "map", "ticket", "coins" ], "example": "chat_bubbles" }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/project/123456789" }, "project_brief": { "allOf": [ { "$ref": "#/components/schemas/ProjectBriefCompact" }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project brief associated with this project.", "nullable": true } ] }, "created_from_template": { "allOf": [ { "$ref": "#/components/schemas/ProjectTemplateCompact" }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project template from which this project was created. If the project was not created from a template, this field will be null.", "nullable": true } ] }, "workspace": { "allOf": [ { "$ref": "#/components/schemas/WorkspaceCompact" }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace or organization this project is associated with. Once created, projects cannot be moved to a different workspace. This attribute can only be specified at creation time. If the workspace for your project is an organization, you must also supply a `team` in the request body." } ] } } } ] }, "ProjectSectionInsertRequest": { "type": "object", "properties": { "section": { "description": "The section to reorder.", "type": "string", "example": "321654" }, "before_section": { "description": "Insert the given section immediately before the section specified by this parameter.", "type": "string", "example": "86420" }, "after_section": { "description": "Insert the given section immediately after the section specified by this parameter.", "type": "string", "example": "987654" } }, "required": [ "section" ] }, "ProjectStatusBase": { "allOf": [ { "$ref": "#/components/schemas/ProjectStatusCompact" }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, "ProjectStatusCompact": { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, "ProjectStatusRequest": { "$ref": "#/components/schemas/ProjectStatusBase" }, "ProjectStatusResponse": { "allOf": [ { "$ref": "#/components/schemas/ProjectStatusBase" }, { "type": "object", "properties": { "author": { "$ref": "#/components/schemas/UserCompact" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "$ref": "#/components/schemas/UserCompact" }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, "ProjectTemplateCompact": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, "ProjectTemplateBase": { "allOf": [ { "$ref": "#/components/schemas/ProjectTemplateCompact" }, { "type": "object", "properties": { "description": { "description": "Free-form textual information associated with the project template", "type": "string", "example": "These are things we need to pack for a trip." }, "html_description": { "description": "The description of the project template with formatting as HTML.", "type": "string", "example": "These are things we need to pack for a trip." }, "public": { "description": "True if the project template is public to its team.", "type": "boolean", "example": false }, "owner": { "description": "The current owner of the project template, may be null.", "allOf": [ { "$ref": "#/components/schemas/UserCompact" }, { "type": "object", "nullable": true } ] }, "team": { "allOf": [ { "$ref": "#/components/schemas/TeamCompact" } ] }, "requested_dates": { "description": "Array of date variables in this project template. Calendar dates must be provided for these variables when instantiating a project.", "type": "array", "items": { "$ref": "#/components/schemas/DateVariableCompact" }, "readOnly": true }, "color": { "description": "Color of the project template.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", null ], "example": "light-green" }, "requested_roles": { "description": "Array of template roles in this project template. User Ids can be provided for these variables when instantiating a project to assign template tasks to the user.", "type": "array", "items": { "$ref": "#/components/schemas/TemplateRole" } } } } ] }, "ProjectTemplateResponse": { "allOf": [ { "$ref": "#/components/schemas/ProjectTemplateBase" } ] }, "ProjectTemplateInstantiateProjectRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "description": "The name of the new project.", "type": "string", "example": "New Project Name" }, "team": { "description": "*Optional*. Sets the team of the new project. If the project template exists in an _organization_, you may specify a value for `team`. If no value is provided then it defaults to the same team as the project template.", "type": "string", "example": "12345" }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "deprecated": true, "type": "boolean", "example": true }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "is_strict": { "description": "*Optional*. If set to `true`, the endpoint returns an \"Unprocessable Entity\" error if you fail to provide a calendar date value for any date variable. If set to `false`, a default date is used for each unfulfilled date variable (e.g., the current date is used as the Start Date of a project).", "type": "boolean", "example": true }, "requested_dates": { "description": "*Conditional*. Array of mappings of date variables to calendar dates. This property is required in the instantiation request if the project template includes dates (e.g., a start date on a task).", "type": "array", "items": { "$ref": "#/components/schemas/DateVariableRequest" } }, "requested_roles": { "description": "Array of mappings of template roles to user ids", "type": "array", "items": { "$ref": "#/components/schemas/RequestedRoleRequest" } } } }, "DateVariableCompact": { "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the date field in the project template. A value of `1` refers to the project start date, while `2` refers to the project due date.", "type": "string", "readOnly": true, "example": "1" }, "name": { "description": "The name of the date variable.", "type": "string", "readOnly": true, "example": "Start Date" }, "description": { "description": "The description of what the date variable is used for when instantiating a project.", "type": "string", "readOnly": true, "example": "Choose a start date for your project." } } }, "DateVariableRequest": { "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the date field in the project template. A value of `1` refers to the project start date, while `2` refers to the project due date.", "type": "string", "example": "1" }, "value": { "description": "The date with which the date variable should be replaced when instantiating a project. This takes a date with `YYYY-MM-DD` format.", "type": "string", "nullable": true, "format": "date-time", "example": "2022-01-01" } } }, "RequestedRoleRequest": { "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the template role in the project template.", "type": "string", "example": "1" }, "value": { "description": "The user id that should be assigned to the template role.", "type": "string", "example": "123" } } }, "ProjectSaveAsTemplateRequest": { "type": "object", "required": [ "name", "public" ], "properties": { "name": { "description": "The name of the new project template.", "type": "string", "example": "New Project Template" }, "team": { "description": "Sets the team of the new project template. If the project exists in an organization, specify team and not workspace.", "type": "string", "example": "12345" }, "workspace": { "description": "Sets the workspace of the new project template. Only specify workspace if the project exists in a workspace.", "type": "string", "example": "12345" }, "public": { "description": "Sets the project template to public to its team.", "type": "boolean", "example": true } } }, "RuleTriggerRequest": { "type": "object", "properties": { "resource": { "description": "The ID of the resource. For the duration of the beta, this resource is always a task, and this task must exist in the project in which the rule is created.", "type": "string", "example": "12345" }, "action_data": { "type": "object", "additionalProperties": true, "description": "The dynamic keys and values of the request. These fields are intended to be used in the action for the rule associated with this trigger.", "example": { "jira_ticket_name": "Test", "jira_ticket_id": "123" } } }, "required": [ "resource", "action_data" ] }, "RuleTriggerResponse": { "type": "object", "properties": { "message": { "description": "Message providing more detail about the result", "type": "string", "example": "Successfully saved the payload and ran the rule" } } }, "RemoveCustomFieldSettingRequest": { "type": "object", "required": [ "custom_field" ], "properties": { "custom_field": { "description": "The custom field to remove from this portfolio.", "type": "string", "example": "14916" } } }, "RemoveFollowersRequest": { "type": "object", "required": [ "followers" ], "properties": { "followers": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "521621,621373" } } }, "RemoveMembersRequest": { "type": "object", "required": [ "members" ], "properties": { "members": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "521621,621373" } } }, "ResourceExportFilters": { "type": "object", "description": "Filters to apply to a resource that will be exported. These filters can be used to narrow down the resources that are included in the export.", "properties": { "assigned_by.any": { "description": "Filter by the users who assigned the resource. This array accepts a list of user GIDs. This is only applicable to tasks.", "type": "array", "items": { "type": "string", "example": "12345" } }, "assignee.any": { "description": "Filter by the users who are assigned to the resource. This array accepts a list of user GIDs. This is only applicable to tasks.", "type": "array", "items": { "type": "string", "example": "12345" } }, "commented_on_by.any": { "description": "Filter by the users who commented on the resource. This array accepts a list of user GIDs.", "type": "array", "items": { "type": "string", "example": "12345" } }, "created_at.after": { "description": "Filter results to resources created after a specified date and time.", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "created_at.before": { "description": "Filter results to resources created before a specified date and time.", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "created_by.any": { "description": "Filter by the users who created the resource. This array accepts a list of user GIDs.", "type": "array", "items": { "type": "string", "example": "12345" } }, "followers.any": { "description": "Filter by the users who are following the resource. This array accepts a list of user GIDs.", "type": "array", "items": { "type": "string", "example": "12345" } }, "liked_by.any": { "description": "Filter by the users who liked the resource. This array accepts a list of user GIDs.", "type": "array", "items": { "type": "string", "example": "12345" } }, "modified_at.after": { "description": "Filter results to resources modified after a specified date and time.", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "modified_at.before": { "description": "Filter results to resources modified before a specified date and time.", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" } } }, "ResourceExportRequestParameter": { "type": "object", "properties": { "resource_type": { "type": "string", "description": "The type of the resource to be exported. This can be a task, team, or message.", "example": "task" }, "filters": { "$ref": "#/components/schemas/ResourceExportFilters" }, "fields": { "type": "array", "description": "An array of fields to include for the resource type. If not provided, all non-optional fields for the resource type will be included. This conforms to the fields optional parameter available for all Asana endpoints which is documented [here](https://developers.asana.com/docs/inputoutput-options)", "items": { "type": "string", "example": "gid" } } } }, "ResourceExportRequest": { "type": "object", "description": "A *resource_export* request starts a job to bulk export objects for one or more resources.", "properties": { "workspace": { "type": "string", "description": "Gid of a workspace.", "example": "12345" }, "export_request_parameters": { "type": "array", "description": "An object containing the parameters for the export request. The keys of this object are the GIDs of the resources to be exported. The values are objects with additional parameters for each resource.", "items": { "$ref": "#/components/schemas/ResourceExportRequestParameter" } } } }, "ResourceExportCompact": { "description": "A *resource_export* object represents a request to bulk export objects for one or more resources.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "export_request", "x-insert-after": "gid" }, "created_at": { "description": "The time at which the resource export object was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin [JSON Lines](https://jsonlines.org/) format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or failed.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/object_export/7588024658887731/download/ object_export_2563645399633793_7588024658887731_2023018-201726.jsonl.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Credential=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host" }, "completed_at": { "description": "The time at which this resource was completed. This will be null if the export is still in progress.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } }, "ResourceExportResponse": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "job", "x-insert-after": "gid" }, "resource_subtype": { "description": "A *resource_export* object represents a request to bulk export objects for one or more resources.", "type": "string", "readOnly": true, "example": "export_request" }, "status": { "description": "The current status of this job.", "type": "string", "enum": [ "not_started", "in_progress", "succeeded", "failed" ], "readOnly": true, "example": "succeeded" }, "new_resource_export": { "$ref": "#/components/schemas/ResourceExportCompact" } } }, "GraphExportRequest": { "type": "object", "description": "A *graph_export* request starts a job to export data starting from a parent object.", "properties": { "parent": { "description": "Globally unique ID of the parent object: goal, project, portfolio, or team.", "type": "string", "example": "181636" } } }, "GraphExportCompact": { "description": "A *graph_export* object represents a request to export the data starting from a parent object", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "graph_export", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin JSON format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or\nfailed. If present, this URL may only be valid for 1 hour from\nthe time of retrieval. You should avoid persisting this URL\nsomewhere and rather refresh on demand to ensure you do not keep\nstale URLs.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/domain_export/7588024658887731/download/ domain_export_2563645399633793_7588024658887731_2023018-201726.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Content-Sha256=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host&x-id=GetObject#_=_" }, "completed_at": { "description": "The time at which this resource was completed.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } }, "GraphExportResponse": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "job", "x-insert-after": "gid" }, "resource_subtype": { "description": "A *graph_export* object represents a request to export the data starting from a parent object", "type": "string", "readOnly": true, "example": "graph_export_request" }, "status": { "description": "The current status of this job.", "type": "string", "enum": [ "not_started", "in_progress", "succeeded", "failed" ], "readOnly": true, "example": "succeeded" }, "new_graph_export": { "$ref": "#/components/schemas/GraphExportCompact" } } }, "SectionBase": { "$ref": "#/components/schemas/SectionCompact" }, "SectionCompact": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, "SectionRequest": { "type": "object", "properties": { "name": { "description": "The text to be displayed as the section name. This cannot be an empty string.", "type": "string", "example": "Next Actions" }, "insert_before": { "description": "An existing section within this project before which the added section should be inserted. Cannot be provided together with insert_after.", "type": "string", "example": "86420" }, "insert_after": { "description": "An existing section within this project after which the added section should be inserted. Cannot be provided together with insert_before.", "type": "string", "example": "987654" } }, "required": [ "name" ] }, "SectionResponse": { "allOf": [ { "$ref": "#/components/schemas/SectionBase" }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "project": { "$ref": "#/components/schemas/ProjectCompact" }, "projects": { "description": "*Deprecated - please use project instead*", "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/ProjectCompact" } } } } ] }, "SectionTaskInsertRequest": { "type": "object", "properties": { "task": { "description": "The task to add to this section.", "type": "string", "example": "123456" }, "insert_before": { "description": "An existing task within this section before which the added task should be inserted. Cannot be provided together with insert_after.", "type": "string", "example": "86420" }, "insert_after": { "description": "An existing task within this section after which the added task should be inserted. Cannot be provided together with insert_before.", "type": "string", "example": "987654" } }, "required": [ "task" ] }, "StatusUpdateBase": { "allOf": [ { "$ref": "#/components/schemas/StatusUpdateCompact" }, { "type": "object", "required": [ "text", "status_type" ], "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "status_type": { "description": "The type associated with the status update. This represents the current state of the object this object is on.", "type": "string", "enum": [ "on_track", "at_risk", "off_track", "on_hold", "complete", "achieved", "partial", "missed", "dropped" ] } } } ] }, "StatusUpdateCompact": { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, "StatusUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/StatusUpdateBase" }, { "type": "object", "required": [ "parent" ], "properties": { "parent": { "allOf": [ { "type": "string", "description": "The id of parent to send this status update to. This can be a project, goal or portfolio." } ] } } } ] }, "StatusUpdateResponse": { "allOf": [ { "$ref": "#/components/schemas/StatusUpdateBase" }, { "type": "object", "properties": { "author": { "$ref": "#/components/schemas/UserCompact" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "$ref": "#/components/schemas/UserCompact" }, "hearted": { "description": "*Deprecated - please use liked instead* True if the status is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this status.", "type": "array", "items": { "$ref": "#/components/schemas/Like" }, "readOnly": true }, "liked": { "description": "True if the status is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this status.", "type": "array", "items": { "$ref": "#/components/schemas/Like" }, "readOnly": true }, "reaction_summary": { "description": "Summary of emoji reactions on this status.", "type": "array", "items": { "$ref": "#/components/schemas/ReactionSummaryItemCompact" }, "readOnly": true }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this status.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this status.", "type": "integer", "example": 5, "readOnly": true }, "parent": { "allOf": [ { "$ref": "#/components/schemas/ProjectCompact" }, { "type": "object", "description": "The parent of the status update. This can be a project, goal or portfolio, and indicates that this status was sent on that object." } ] } } } ] }, "StoryBase": { "description": "A story represents an activity associated with an object in the Asana system.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "story", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "comment_added" }, "text": { "description": "The plain text of the comment to add. Cannot be used with html_text.", "type": "string", "example": "This is a comment." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). HTML formatted text for a comment. This will not include the name of the creator.", "type": "string", "example": "This is a comment." }, "is_pinned": { "description": "*Conditional*. Whether the story should be pinned on the resource.", "type": "boolean", "example": false }, "sticker_name": { "description": "The name of the sticker in this story. `null` if there is no sticker.", "type": "string", "enum": [ "green_checkmark", "people_dancing", "dancing_unicorn", "heart", "party_popper", "people_waving_flags", "splashing_narwhal", "trophy", "yeti_riding_unicorn", "celebrating_people", "determined_climbers", "phoenix_spreading_love" ], "example": "dancing_unicorn" } } }, "StoryCompact": { "description": "A story represents an activity associated with an object in the Asana system.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "story", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "$ref": "#/components/schemas/UserCompact" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "comment_added" }, "text": { "description": "*Create-only*. Human-readable text for the story or comment.\nThis will not include the name of the creator.\n*Note: This is not guaranteed to be stable for a given type of story. For example, text for a reassignment may not always say \u201cassigned to \u2026\u201d as the text for a story can both be edited and change based on the language settings of the user making the request.*\nUse the `resource_subtype` property to discover the action that created the story.", "type": "string", "example": "marked today" } } }, "StoryRequest": { "$ref": "#/components/schemas/StoryBase" }, "StoryResponse": { "allOf": [ { "$ref": "#/components/schemas/StoryBase" }, { "type": "object", "properties": { "created_by": { "$ref": "#/components/schemas/UserCompact" }, "type": { "type": "string", "enum": [ "comment", "system" ], "readOnly": true, "example": "comment" }, "is_editable": { "description": "*Conditional*. Whether the text of the story can be edited after creation.", "type": "boolean", "readOnly": true, "example": false }, "is_edited": { "description": "*Conditional*. Whether the text of the story has been edited after creation.", "type": "boolean", "readOnly": true, "example": false }, "hearted": { "description": "*Deprecated - please use likes instead*\n*Conditional*. True if the story is hearted by the authorized user, false if not.", "type": "boolean", "readOnly": true, "example": false }, "hearts": { "description": "*Deprecated - please use likes instead*\n\n*Conditional*. Array of likes for users who have hearted this story.", "type": "array", "items": { "$ref": "#/components/schemas/Like" }, "readOnly": true }, "num_hearts": { "description": "*Deprecated - please use likes instead*\n\n*Conditional*. The number of users who have hearted this story.", "type": "integer", "readOnly": true, "example": 5 }, "liked": { "description": "*Conditional*. True if the story is liked by the authorized user, false if not.", "type": "boolean", "readOnly": true, "example": false }, "likes": { "description": "*Conditional*. Array of likes for users who have liked this story.", "type": "array", "items": { "$ref": "#/components/schemas/Like" }, "readOnly": true }, "num_likes": { "description": "*Conditional*. The number of users who have liked this story.", "type": "integer", "readOnly": true, "example": 5 }, "reaction_summary": { "description": "Summary of emoji reactions on this story.", "type": "array", "items": { "$ref": "#/components/schemas/ReactionSummaryItemCompact" }, "readOnly": true }, "previews": { "description": "

Full object requires scope: attachments:read

\n\n*Conditional*. A collection of previews to be displayed in the story.\n\n*Note: This property only exists for comment stories.*", "type": "array", "items": { "$ref": "#/components/schemas/Preview" }, "readOnly": true }, "old_name": { "description": "*Conditional* The previous name of the task before a name change.", "type": "string", "example": "This was the old name" }, "new_name": { "description": "*Conditional* The updated name of the task after a name change.", "type": "string", "nullable": true, "readOnly": true, "example": "This is the new name" }, "old_dates": { "$ref": "#/components/schemas/StoryResponseDates" }, "new_dates": { "$ref": "#/components/schemas/StoryResponseDates" }, "old_resource_subtype": { "description": "*Conditional*", "type": "string", "readOnly": true, "example": "default_task" }, "new_resource_subtype": { "description": "*Conditional*", "type": "string", "readOnly": true, "example": "milestone" }, "story": { "description": "*Conditional*", "$ref": "#/components/schemas/StoryCompact", "readOnly": true }, "assignee": { "description": "*Conditional*", "$ref": "#/components/schemas/UserCompact", "readOnly": true }, "follower": { "description": "*Conditional*", "$ref": "#/components/schemas/UserCompact", "readOnly": true }, "old_section": { "description": "*Conditional*", "$ref": "#/components/schemas/SectionCompact", "readOnly": true }, "new_section": { "description": "*Conditional*", "$ref": "#/components/schemas/SectionCompact", "readOnly": true }, "task": { "description": "*Conditional*", "$ref": "#/components/schemas/TaskCompact", "readOnly": true }, "project": { "description": "*Conditional*", "$ref": "#/components/schemas/ProjectCompact", "readOnly": true }, "tag": { "description": "*Conditional*", "$ref": "#/components/schemas/TagCompact", "readOnly": true }, "custom_field": { "description": "*Conditional*", "$ref": "#/components/schemas/CustomFieldCompact", "readOnly": true }, "old_text_value": { "description": "*Conditional* The previous value of a text-type field before it was updated.", "type": "string", "readOnly": true, "example": "This was the old text" }, "new_text_value": { "description": "*Conditional* The new value of a text-type field after it was updated.", "type": "string", "readOnly": true, "example": "This is the new text" }, "old_number_value": { "description": "*Conditional* The previous value of a number-type custom field before the update.", "type": "integer", "nullable": true, "readOnly": true, "example": 1 }, "new_number_value": { "description": "*Conditional* The new value of a number-type custom field after the update.", "type": "integer", "readOnly": true, "example": 2 }, "old_enum_value": { "description": "*Conditional*", "$ref": "#/components/schemas/EnumOption", "readOnly": true }, "new_enum_value": { "description": "*Conditional*", "$ref": "#/components/schemas/EnumOption", "readOnly": true }, "old_date_value": { "allOf": [ { "$ref": "#/components/schemas/StoryResponseDates" }, { "description": "*Conditional*. The old value of a date custom field story." } ], "readOnly": true }, "new_date_value": { "allOf": [ { "$ref": "#/components/schemas/StoryResponseDates" }, { "description": "*Conditional* The new value of a date custom field story." } ], "readOnly": true }, "old_people_value": { "description": "*Conditional*. The old value of a people custom field story.", "type": "array", "items": { "$ref": "#/components/schemas/UserCompact" }, "readOnly": true }, "new_people_value": { "description": "*Conditional*. The new value of a people custom field story.", "type": "array", "items": { "$ref": "#/components/schemas/UserCompact" }, "readOnly": true }, "old_multi_enum_values": { "description": "*Conditional*. The old value of a multi-enum custom field story.", "type": "array", "items": { "$ref": "#/components/schemas/EnumOption" }, "readOnly": true }, "new_multi_enum_values": { "description": "*Conditional*. The new value of a multi-enum custom field story.", "type": "array", "items": { "$ref": "#/components/schemas/EnumOption" }, "readOnly": true }, "new_approval_status": { "description": "*Conditional*. The new value of approval status.", "type": "string", "readOnly": true, "example": "approved" }, "old_approval_status": { "description": "*Conditional*. The old value of approval status.", "type": "string", "readOnly": true, "example": "pending" }, "duplicate_of": { "description": "*Conditional*", "$ref": "#/components/schemas/TaskCompact", "readOnly": true }, "duplicated_from": { "description": "*Conditional*", "$ref": "#/components/schemas/TaskCompact", "readOnly": true }, "dependency": { "description": "*Conditional*", "$ref": "#/components/schemas/TaskCompact", "readOnly": true }, "source": { "description": "The component of the Asana product the user used to trigger the story.", "type": "string", "enum": [ "web", "email", "mobile", "api", "unknown" ], "readOnly": true, "example": "web" }, "target": { "allOf": [ { "$ref": "#/components/schemas/TaskCompact" }, { "type": "object", "readOnly": true, "description": "The object this story is associated with. Currently may only be a task." } ] } } } ] }, "StoryResponseDates": { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, "TagBase": { "allOf": [ { "$ref": "#/components/schemas/TagCompact" }, { "type": "object", "properties": { "color": { "type": "string", "description": "Color of the tag.", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", null ], "example": "light-green" }, "notes": { "description": "Free-form textual information associated with the tag (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." } } } ] }, "TagCompact": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "TagCreateTagForWorkspaceRequest": { "allOf": [ { "$ref": "#/components/schemas/TagBase" }, { "type": "object", "properties": { "followers": { "type": "array", "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "items": { "type": "string" }, "example": [ "12345", "42563" ] } } } ] }, "TagBaseRequest": { "$ref": "#/components/schemas/TagBase" }, "TagCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/TagBaseRequest" }, { "type": "object", "properties": { "followers": { "type": "array", "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "items": { "type": "string" }, "example": [ "12345", "42563" ] }, "workspace": { "type": "string", "x-env-variable": true, "description": "Gid of an object.", "example": "12345" } } } ] }, "TagUpdateRequest": { "$ref": "#/components/schemas/TagBaseRequest" }, "TagResponse": { "allOf": [ { "$ref": "#/components/schemas/TagBase" }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "followers": { "description": "Array of users following this tag.", "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/UserCompact" } }, "workspace": { "$ref": "#/components/schemas/WorkspaceCompact" }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" } } } ] }, "TaskAddFollowersRequest": { "type": "object", "properties": { "followers": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "array", "items": { "type": "string" }, "example": [ "13579", "321654" ] } }, "required": [ "followers" ] }, "TaskAddProjectRequest": { "type": "object", "properties": { "project": { "description": "The project to add the task to.", "type": "string", "example": "13579" }, "insert_after": { "description": "A task in the project to insert the task after, or `null` to insert at the beginning of the list.", "type": "string", "nullable": true, "example": "124816" }, "insert_before": { "description": "A task in the project to insert the task before, or `null` to insert at the end of the list.", "type": "string", "nullable": true, "example": "432134" }, "section": { "description": "A section in the project to insert the task into. The task will be inserted at the bottom of the section.", "type": "string", "nullable": true, "example": "987654" } }, "required": [ "project" ] }, "TaskAddTagRequest": { "type": "object", "properties": { "tag": { "description": "The tag's gid to add to the task.", "type": "string", "example": "13579" } }, "required": [ "tag" ] }, "TaskBase": { "allOf": [ { "$ref": "#/components/schemas/TaskCompact" }, { "type": "object", "properties": { "approval_status": { "type": "string", "description": "*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.", "enum": [ "pending", "approved", "rejected", "changes_requested" ], "example": "pending" }, "assignee_status": { "description": "*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to \"inbox\" or \"upcoming\" inserts it at the top of the section, while the other options will insert at the bottom.", "type": "string", "enum": [ "today", "upcoming", "later", "new", "inbox" ], "example": "upcoming" }, "completed": { "description": "True if the task is currently marked complete, false if not.", "type": "boolean", "example": false }, "completed_at": { "description": "The time at which this task was completed, or null if the task is incomplete.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "$ref": "#/components/schemas/UserCompact" }, { "readOnly": true, "nullable": true } ] }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "dependencies": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.", "type": "array", "items": { "$ref": "#/components/schemas/AsanaResource" }, "readOnly": true }, "dependents": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.", "type": "array", "items": { "$ref": "#/components/schemas/AsanaResource" }, "readOnly": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.147Z", "nullable": true }, "due_on": { "description": "The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.", "type": "string", "format": "date", "example": "2019-09-15", "nullable": true }, "external": { "description": "*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).\nThe external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.", "type": "object", "properties": { "gid": { "type": "string", "example": "1234" }, "data": { "type": "string", "example": "A blob of information." } }, "example": { "gid": "my_gid", "data": "A blob of information" } }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "hearted": { "description": "*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this task.", "type": "array", "items": { "$ref": "#/components/schemas/Like" }, "readOnly": true }, "is_rendered_as_separator": { "description": "[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`. This parameter only applies to regular tasks with `resource_subtype` of `default_task`. Tasks with `resource_subtype` of `milestone`, `approval`, or custom task types will not have this property and cannot be rendered as separators.", "type": "boolean", "example": false, "readOnly": true }, "liked": { "description": "True if the task is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this task.", "type": "array", "items": { "$ref": "#/components/schemas/Like" }, "readOnly": true }, "memberships": { "description": "

Full object requires scope: projects:read, project_sections:read

\n\n*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.", "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/ProjectCompact" }, "section": { "$ref": "#/components/schemas/SectionCompact" } } } }, "modified_at": { "description": "The time at which this task was last modified.\n\nThe following conditions will change `modified_at`:\n\n- story is created on a task\n- story is trashed on a task\n- attachment is trashed on a task\n- task is assigned or unassigned\n- custom field value is changed\n- the task itself is trashed\n- Or if any of the following fields are updated:\n - completed\n - name\n - due_date\n - description\n - attachments\n - items\n - schedule_status\n\nThe following conditions will _not_ change `modified_at`:\n\n- moving to a new container (project, portfolio, etc)\n- comments being added to the task (but the stories they generate\n _will_ affect `modified_at`)", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "name": { "description": "Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Buy catnip" }, "notes": { "description": "Free-form textual information associated with the task (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this task.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this task.", "type": "integer", "example": 5, "readOnly": true }, "num_subtasks": { "description": "[Opt In](/docs/inputoutput-options). The number of subtasks on this task.\n", "type": "integer", "example": 3, "readOnly": true }, "start_at": { "description": "Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.\n*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*", "type": "string", "nullable": true, "format": "date-time", "example": "2019-09-14T02:06:58.147Z" }, "start_on": { "description": "The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.\n*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "actual_time_minutes": { "description": "

Full object requires scope: time_tracking_entries:read

\n\nThis value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.", "type": "number", "example": 200, "readOnly": true, "nullable": true } } } ] }, "TaskCompact": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "TaskTemplateCompact": { "description": "A *task template* is an object that allows new tasks to be created with a predefined setup.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task_template", "x-insert-after": "gid" }, "name": { "description": "Name of the task template.", "type": "string", "example": "Packing list" } } }, "TaskTemplateBase": { "allOf": [ { "$ref": "#/components/schemas/TaskTemplateCompact" } ] }, "TaskTemplateRecipeCompact": { "type": "object", "properties": { "name": { "description": "Name of the task that will be created from this template.", "type": "string", "example": "Bug Report" }, "task_resource_subtype": { "type": "string", "description": "The subtype of the task that will be created from this template.", "enum": [ "default_task", "milestone_task", "approval_task" ], "example": "default_task" } } }, "TaskTemplateRecipe": { "allOf": [ { "$ref": "#/components/schemas/TaskTemplateRecipeCompact" }, { "type": "object", "properties": { "description": { "description": "Description of the task that will be created from this template.", "type": "string", "example": "Please describe the bug you found and how to reproduce it." }, "html_description": { "description": "HTML description of the task that will be created from this template.", "type": "string", "example": "Please describe the bug you found and how to reproduce it." }, "memberships": { "description": "Array of projects that the task created from this template will be added to", "type": "array", "items": { "$ref": "#/components/schemas/ProjectCompact" } }, "relative_start_on": { "nullable": true, "description": "The number of days after the task has been instantiated on which that the task will start", "type": "integer", "example": 1 }, "relative_due_on": { "nullable": true, "description": "The number of days after the task has been instantiated on which that the task will be due", "type": "integer", "example": 2 }, "due_time": { "nullable": true, "description": "The time of day that the task will be due", "type": "string", "example": "13:15:00.000Z" }, "dependencies": { "description": "Array of task templates that the task created from this template will depend on", "type": "array", "items": { "$ref": "#/components/schemas/TaskTemplateRecipeCompact" } }, "dependents": { "description": "Array of task templates that will depend on the task created from this template", "type": "array", "items": { "$ref": "#/components/schemas/TaskTemplateRecipeCompact" } }, "followers": { "description": "Array of users that will be added as followers to the task created from this template", "type": "array", "items": { "$ref": "#/components/schemas/UserCompact" } }, "attachments": { "description": "Array of attachments that will be added to the task created from this template", "type": "array", "items": { "$ref": "#/components/schemas/AttachmentCompact" } }, "subtasks": { "description": "Array of subtasks that will be added to the task created from this template", "type": "array", "items": { "$ref": "#/components/schemas/TaskTemplateRecipeCompact" } }, "custom_fields": { "description": "Array of custom fields that will be added to the task created from this template", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldCompact" } } } } ] }, "TaskTemplateResponse": { "allOf": [ { "$ref": "#/components/schemas/TaskTemplateBase" }, { "type": "object", "properties": { "name": { "description": "Name of the task template.", "type": "string", "example": "Bug Report Template" }, "project": { "description": "The project that this task template belongs to.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ProjectCompact" } ] }, "template": { "description": "The configuration for the task that will be created from this template.", "allOf": [ { "$ref": "#/components/schemas/TaskTemplateRecipe" } ] }, "created_by": { "description": "The user who created this task template.", "allOf": [ { "$ref": "#/components/schemas/UserCompact" } ] }, "created_at": { "description": "The time at which this task template was created.", "type": "string", "format": "date-time", "example": "2019-01-01T00:00:00.000Z" } } } ] }, "TaskCountResponse": { "description": "A response object returned from the task count endpoint.", "type": "object", "properties": { "num_tasks": { "description": "The number of tasks in a project.", "type": "integer", "example": 200 }, "num_incomplete_tasks": { "description": "The number of incomplete tasks in a project.", "type": "integer", "example": 50 }, "num_completed_tasks": { "description": "The number of completed tasks in a project.", "type": "integer", "example": 150 }, "num_milestones": { "description": "The number of milestones in a project.", "type": "integer", "example": 10 }, "num_incomplete_milestones": { "description": "The number of incomplete milestones in a project.", "type": "integer", "example": 7 }, "num_completed_milestones": { "description": "The number of completed milestones in a project.", "type": "integer", "example": 3 } } }, "TaskDuplicateRequest": { "type": "object", "properties": { "name": { "description": "The name of the new task.", "type": "string", "example": "New Task Name" }, "include": { "description": "A comma-separated list of fields that will be duplicated to the new task.\n##### Fields\n- assignee\n- attachments\n- dates\n- dependencies\n- followers\n- notes\n- parent\n- projects\n- subtasks\n- tags", "type": "string", "pattern": "([notes|assignee|subtasks|attachments|tags|followers|projects|dates|dependencies|parent])(,\\1)*", "example": [ "notes,assignee,subtasks,attachments,tags,followers,projects,dates,dependencies,parent" ] } } }, "TaskRemoveFollowersRequest": { "type": "object", "properties": { "followers": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "array", "items": { "type": "string" }, "example": [ "13579", "321654" ] } }, "required": [ "followers" ] }, "TaskRemoveProjectRequest": { "type": "object", "properties": { "project": { "description": "The project to remove the task from.", "type": "string", "example": "13579" } }, "required": [ "project" ] }, "TaskRemoveTagRequest": { "type": "object", "properties": { "tag": { "description": "The tag's gid to remove from the task.", "type": "string", "example": "13579" } }, "required": [ "tag" ] }, "TaskTemplateInstantiateTaskRequest": { "type": "object", "properties": { "name": { "description": "The name of the new task. If not provided, the name of the task template will be used.", "type": "string", "example": "New Task" } } }, "TaskRequest": { "allOf": [ { "$ref": "#/components/schemas/TaskBase" }, { "type": "object", "properties": { "assignee": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "Gid of a user.", "example": "12345", "nullable": true }, "assignee_section": { "nullable": true, "type": "string", "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list.", "example": "12345" }, "custom_fields": { "description": "An object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, object, or array (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.", "type": "object", "additionalProperties": { "type": "string", "description": "\"{custom_field_gid}\" => Value (can be text, a number, etc.). For date, use format \"YYYY-MM-DD\" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z)." }, "example": { "5678904321": "On Hold", "4578152156": "Not Started" } }, "followers": { "type": "array", "description": "*Create-Only* An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user. In order to change followers on an existing task use `addFollowers` and `removeFollowers`.", "items": { "type": "string", "description": "Gid of a user." }, "example": [ "12345" ] }, "parent": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "Gid of a task.", "example": "12345", "nullable": true }, "projects": { "type": "array", "description": "*Create-Only* Array of project gids. In order to change projects on an existing task use `addProject` and `removeProject`.", "items": { "type": "string", "description": "Gid of a project." }, "example": [ "12345" ] }, "tags": { "type": "array", "description": "*Create-Only* Array of tag gids. In order to change tags on an existing task use `addTag` and `removeTag`.", "items": { "type": "string", "description": "Gid of a tag." }, "example": [ "12345" ] }, "workspace": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "Gid of a workspace.", "example": "12345" }, "custom_type": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "GID or globally-unique identifier of a custom_type.", "example": "12345", "nullable": true }, "custom_type_status_option": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "GID or globally-unique identifier of a custom_type_status_option", "example": "12345", "nullable": true } } } ] }, "TaskResponse": { "allOf": [ { "$ref": "#/components/schemas/TaskBase" }, { "type": "object", "properties": { "assignee": { "allOf": [ { "$ref": "#/components/schemas/UserCompact" }, { "nullable": true } ] }, "assignee_section": { "allOf": [ { "$ref": "#/components/schemas/SectionCompact" }, { "type": "object", "nullable": true, "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list." } ] }, "custom_fields": { "description": "Array of custom field values applied to the task. These represent the custom field values recorded on this project for a particular custom field. For example, these custom field values will contain an `enum_value` property for custom fields of type `enum`, a `text_value` property for custom fields of type `text`, and so on. Please note that the `gid` returned on each custom field value *is identical* to the `gid` of the custom field, which allows referencing the custom field metadata through the `/custom_fields/custom_field_gid` endpoint.", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldResponse" }, "readOnly": true }, "custom_type": { "allOf": [ { "$ref": "#/components/schemas/CustomTypeCompact" }, { "nullable": true } ] }, "custom_type_status_option": { "allOf": [ { "$ref": "#/components/schemas/CustomTypeStatusOptionCompact" }, { "nullable": true } ] }, "followers": { "description": "Array of users following this task.", "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/UserCompact" } }, "parent": { "allOf": [ { "$ref": "#/components/schemas/TaskCompact" }, { "type": "object", "readOnly": true, "description": "The parent of this task, or `null` if this is not a subtask. This property cannot be modified using a PUT request but you can change it with the `setParent` endpoint. You can create subtasks by using the subtasks endpoint.", "nullable": true } ] }, "projects": { "description": "*Create-only.* Array of projects this task is associated with. At task creation time, this array can be used to add the task to many projects at once. After task creation, these associations can be modified using the addProject and removeProject endpoints.", "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/ProjectCompact" } }, "tags": { "description": "Array of tags associated with this task. In order to change tags on an existing task use `addTag` and `removeTag`.", "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/TagCompact" }, "example": [ { "gid": "59746", "name": "Grade A" } ] }, "workspace": { "allOf": [ { "$ref": "#/components/schemas/WorkspaceCompact" }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace this task is associated with. Once created, task cannot be moved to a different workspace. This attribute can only be specified at creation time." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/task/123456789" } } } ] }, "TaskSetParentRequest": { "type": "object", "properties": { "parent": { "description": "The new parent of the task, or `null` for no parent.", "type": "string", "example": "987654" }, "insert_after": { "description": "A subtask of the parent to insert the task after, or `null` to insert at the beginning of the list.", "type": "string", "example": "null" }, "insert_before": { "description": "A subtask of the parent to insert the task before, or `null` to insert at the end of the list.", "type": "string", "example": "124816" } }, "required": [ "parent" ] }, "TeamAddUserRequest": { "type": "object", "description": "A user identification object for specification with the addUser/removeUser endpoints.", "properties": { "user": { "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "12345" } } }, "TeamBase": { "$ref": "#/components/schemas/TeamCompact" }, "TeamCompact": { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, "TeamMembershipBase": { "$ref": "#/components/schemas/TeamMembershipCompact" }, "TeamMembershipCompact": { "description": "This object represents a user's connection to a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team_membership", "x-insert-after": "gid" }, "user": { "$ref": "#/components/schemas/UserCompact" }, "team": { "$ref": "#/components/schemas/TeamCompact" }, "is_guest": { "type": "boolean", "description": "Describes if the user is a guest in the team.", "example": false }, "is_limited_access": { "type": "boolean", "readOnly": true, "description": "Describes if the user has limited access to the team.", "example": false }, "is_admin": { "type": "boolean", "description": "Describes if the user is a team admin.", "example": false } } }, "TeamMembershipResponse": { "$ref": "#/components/schemas/TeamMembershipBase" }, "TeamRemoveUserRequest": { "type": "object", "description": "A user identification object for specification with the addUser/removeUser endpoints.", "properties": { "user": { "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "12345" } } }, "TeamRequest": { "allOf": [ { "$ref": "#/components/schemas/TeamBase" }, { "type": "object", "properties": { "description": { "description": "The description of the team.\n", "type": "string", "example": "All developers should be members of this team." }, "html_description": { "description": "The description of the team with formatting as HTML.\n", "type": "string", "example": "All developers should be members of this team." }, "organization": { "type": "string", "description": "The organization/workspace the team belongs to. This must be the same organization you are in and cannot be changed once set.\n", "example": "123456789" }, "visibility": { "description": "The visibility of the team to users in the same organization\n", "type": "string", "enum": [ "secret", "request_to_join", "public" ] }, "edit_team_name_or_description_access_level": { "description": "Controls who can edit team name and description\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "edit_team_visibility_or_trash_team_access_level": { "description": "Controls who can edit team visibility and trash teams\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "member_invite_management_access_level": { "description": "Controls who can accept or deny member invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "guest_invite_management_access_level": { "description": "Controls who can accept or deny guest invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "join_request_management_access_level": { "description": "Controls who can accept or deny join team requests for a Membership by Request team. This field can only be updated when the team's `visibility` field is `request_to_join`.\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_member_removal_access_level": { "description": "Controls who can remove team members\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_content_management_access_level": { "description": "Controls who can create and share content with the team\n", "type": "string", "enum": [ "no_restriction", "only_team_admins" ] }, "endorsed": { "description": "Whether the team has been endorsed\n", "type": "boolean", "example": false } } } ] }, "TeamResponse": { "allOf": [ { "$ref": "#/components/schemas/TeamBase" }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the team.\n", "type": "string", "example": "All developers should be members of this team." }, "html_description": { "description": "[Opt In](/docs/inputoutput-options). The description of the team with formatting as HTML.\n", "type": "string", "example": "All developers should be members of this team." }, "organization": { "allOf": [ { "$ref": "#/components/schemas/WorkspaceCompact" }, { "type": "object", "description": "The organization/workspace the team belongs to.\n" } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" }, "visibility": { "description": "The visibility of the team to users in the same organization\n", "type": "string", "enum": [ "secret", "request_to_join", "public" ] }, "edit_team_name_or_description_access_level": { "description": "Controls who can edit team name and description\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "edit_team_visibility_or_trash_team_access_level": { "description": "Controls who can edit team visibility and trash teams\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "member_invite_management_access_level": { "description": "Controls who can accept or deny member invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "guest_invite_management_access_level": { "description": "Controls who can accept or deny guest invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "join_request_management_access_level": { "description": "Controls who can accept or deny join team requests for a Membership by Request team. This field can only be updated when the team's `visibility` field is `request_to_join`.\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_member_removal_access_level": { "description": "Controls who can remove team members\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_content_management_access_level": { "description": "Controls who can create and share content with the team\n", "type": "string", "enum": [ "no_restriction", "only_team_admins" ] }, "endorsed": { "description": "Whether the team has been endorsed\n", "type": "boolean", "example": false } } } ] }, "TemplateRole": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "type": "string", "description": "Name of the template role.", "example": "Designer" } } }, "TimePeriodBase": { "allOf": [ { "$ref": "#/components/schemas/TimePeriodCompact" }, { "type": "object", "properties": { "parent": { "allOf": [ { "$ref": "#/components/schemas/TimePeriodCompact" }, { "nullable": true } ] } } } ] }, "TimePeriodCompact": { "description": "

Full object requires scope: time_periods:read

\n\nA generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_period", "x-insert-after": "gid" }, "end_on": { "type": "string", "description": "The localized end date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-14" }, "start_on": { "type": "string", "description": "The localized start date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-13" }, "period": { "type": "string", "description": "The cadence and index of the time period.", "enum": [ "FY", "H1", "H2", "Q1", "Q2", "Q3", "Q4" ], "example": "Q1" }, "display_name": { "type": "string", "description": "A string representing the cadence code and the fiscal year.", "example": "Q1 FY22" } } }, "TimePeriodResponse": { "$ref": "#/components/schemas/TimePeriodBase" }, "UserBase": { "$ref": "#/components/schemas/UserCompact" }, "UserCompact": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "UserRequest": { "$ref": "#/components/schemas/UserBase" }, "UserBaseResponse": { "allOf": [ { "$ref": "#/components/schemas/UserBase" }, { "type": "object", "properties": { "email": { "type": "string", "format": "email", "readOnly": true, "description": "The user's email address.", "example": "gsanchez@example.com" }, "photo": { "type": "object", "nullable": true, "properties": { "image_21x21": { "type": "string", "format": "uri", "description": "PNG image of the user at 21x21 pixels." }, "image_27x27": { "type": "string", "format": "uri", "description": "PNG image of the user at 27x27 pixels." }, "image_36x36": { "type": "string", "format": "uri", "description": "PNG image of the user at 36x36 pixels." }, "image_60x60": { "type": "string", "format": "uri", "description": "PNG image of the user at 60x60 pixels." }, "image_128x128": { "type": "string", "format": "uri", "description": "PNG image of the user at 128x128 pixels." }, "image_1024x1024": { "type": "string", "format": "uri", "description": "JPEG image of the user at 1024x1024 pixels." } }, "readOnly": true, "description": "A map of the user's profile photo in various sizes, or null if no photo is set. Sizes provided are 21, 27, 36, 60, 128, and 1024. All images are in PNG format, except for 1024 (which is in JPEG format).", "example": { "image_21x21": "https://...", "image_27x27": "https://...", "image_36x36": "https://...", "image_60x60": "https://...", "image_128x128": "https://...", "image_1024x1024": "https://..." } } } } ] }, "UserResponse": { "allOf": [ { "$ref": "#/components/schemas/UserBaseResponse" }, { "type": "object", "properties": { "workspaces": { "description": "Workspaces and organizations this user may access.\nNote\\: The API will only return workspaces and organizations that also contain the authenticated user.", "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceCompact" } }, "custom_fields": { "description": "Array of Custom Fields.", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldCompact" } } } } ] }, "UserTaskListBase": { "$ref": "#/components/schemas/UserTaskListCompact" }, "UserTaskListCompact": { "description": "A user task list represents the tasks assigned to a particular user. It provides API access to a user\u2019s [My tasks](https://asana.com/guide/help/fundamentals/my-tasks) view in Asana.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user_task_list", "x-insert-after": "gid" }, "name": { "description": "The name of the user task list.", "type": "string", "example": "My tasks in My Workspace" }, "owner": { "description": "The owner of the user task list, i.e. the person whose My Tasks is represented by this resource.", "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/UserCompact" } ] }, "workspace": { "description": "The workspace in which the user task list is located.", "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/WorkspaceCompact" } ] } } }, "UserTaskListRequest": { "$ref": "#/components/schemas/UserTaskListBase" }, "UserTaskListResponse": { "$ref": "#/components/schemas/UserTaskListBase" }, "WebhookCompact": { "description": "Webhook objects represent the state of an active subscription for a server to be updated with information from Asana. This schema represents the subscription itself, not the objects that are sent to the server. For information on those please refer to the [event](/reference/events) schema.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "webhook", "x-insert-after": "gid" }, "active": { "description": "If true, the webhook will send events - if false it is considered inactive and will not generate events.", "type": "boolean", "readOnly": true, "example": false }, "resource": { "$ref": "#/components/schemas/AsanaNamedResource" }, "target": { "description": "The URL to receive the HTTP POST.", "type": "string", "format": "uri", "readOnly": true, "example": "https://example.com/receive-webhook/7654" } } }, "WebhookFilter": { "type": "object", "description": "A WebhookFilter can be passed on creation of a webhook in order to filter the types of actions that trigger delivery of an [event](/reference/events)", "properties": { "resource_type": { "type": "string", "description": "The type of the resource which created the event when modified; for example, to filter to changes on regular tasks this field should be set to `task`.", "example": "task" }, "resource_subtype": { "description": "The resource subtype of the resource that the filter applies to. This should be set to the same value as is returned on the `resource_subtype` field on the resources themselves.", "type": "string", "example": "milestone" }, "action": { "type": "string", "description": "The type of change on the **resource** to pass through the filter. For more information refer to `Event.action` in the [event](/reference/events) schema. This can be one of `changed`, `added`, `removed`, `deleted`, and `undeleted` depending on the nature of what has occurred on the resource.", "example": "changed" }, "fields": { "type": "array", "description": "*Conditional.* A whitelist of fields for events which will pass the filter when the resource is changed. These can be any combination of the fields on the resources themselves. This field is only valid for `action` of type `changed`\n*Note: Subscriptions created on higher-level resources such as a Workspace, Team, or Portfolio do not support fields.*", "items": { "type": "string" }, "example": [ "due_at", "due_on", "dependencies" ] } } }, "WebhookRequest": { "type": "object", "properties": { "resource": { "description": "A resource ID to subscribe to. Many Asana resources are valid to create webhooks on, but higher-level resources require filters.", "type": "string", "example": "12345" }, "target": { "description": "The URL to receive the HTTP POST. The full URL will be used to deliver events from this webhook (including parameters) which allows encoding of application-specific state when the webhook is created.", "type": "string", "format": "uri", "example": "https://example.com/receive-webhook/7654?app_specific_param=app_specific_value" }, "filters": { "type": "array", "description": "An array of WebhookFilter objects to specify a whitelist of filters to apply to events from this webhook. If a webhook event passes any of the filters the event will be delivered; otherwise no event will be sent to the receiving server.", "items": { "allOf": [ { "$ref": "#/components/schemas/WebhookFilter" }, { "description": "A set of filters to specify a whitelist for what types of events will be delivered." }, { "type": "object" } ] } } }, "required": [ "resource", "target" ] }, "WebhookResponse": { "allOf": [ { "$ref": "#/components/schemas/WebhookCompact" }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "last_failure_at": { "description": "The timestamp when the webhook last received an error when sending an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "last_failure_content": { "description": "The contents of the last error response sent to the webhook when attempting to deliver events to the target.", "type": "string", "readOnly": true, "example": "500 Server Error\\n\\nCould not complete the request" }, "last_success_at": { "description": "The timestamp when the webhook last successfully sent an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "delivery_retry_count": { "description": "The number of times the webhook has retried delivery of events to the target (resets after a successful attempt).", "type": "integer", "readOnly": true, "example": 3 }, "next_attempt_after": { "description": "The timestamp after which the webhook will next attempt to deliver an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "failure_deletion_timestamp": { "description": "The timestamp when the webhook will be deleted if there is no successful attempt to deliver events to the target", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "filters": { "description": "Whitelist of filters to apply to events from this webhook. If a webhook event passes any of the filters the event will be delivered; otherwise no event will be sent to the receiving server.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/WebhookFilter" }, { "description": "A set of filters to specify a whitelist for what types of events will be delivered." }, { "type": "object" } ] } } } } ] }, "WebhookUpdateRequest": { "type": "object", "properties": { "filters": { "type": "array", "description": "An array of WebhookFilter objects to specify a whitelist of filters to apply to events from this webhook. If a webhook event passes any of the filters the event will be delivered; otherwise no event will be sent to the receiving server.", "items": { "allOf": [ { "$ref": "#/components/schemas/WebhookFilter" }, { "description": "A set of filters to specify a whitelist for what types of events will be delivered." }, { "type": "object" } ] } } } }, "WorkspaceAddUserRequest": { "type": "object", "description": "A user identification object for specification with the addUser/removeUser endpoints.", "properties": { "user": { "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "12345" } } }, "WorkspaceBase": { "$ref": "#/components/schemas/WorkspaceCompact" }, "WorkspaceCompact": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, "WorkspaceMembershipBase": { "$ref": "#/components/schemas/WorkspaceMembershipCompact" }, "WorkspaceMembershipCompact": { "description": "This object determines if a user is a member of a workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace_membership", "x-insert-after": "gid" }, "user": { "$ref": "#/components/schemas/UserCompact" }, "workspace": { "$ref": "#/components/schemas/WorkspaceCompact" } } }, "WorkspaceMembershipRequest": { "$ref": "#/components/schemas/WorkspaceMembershipBase" }, "WorkspaceMembershipResponse": { "allOf": [ { "$ref": "#/components/schemas/WorkspaceMembershipBase" }, { "type": "object", "properties": { "user_task_list": { "$ref": "#/components/schemas/UserTaskListResponse", "description": "The user's \"My tasks\" in the workspace.", "readOnly": true }, "is_active": { "type": "boolean", "readOnly": true, "description": "Indicates whether the user is currently associated with the workspace. Returns `true` for users who have joined the workspace or have been invited but not yet accepted." }, "is_admin": { "type": "boolean", "readOnly": true, "description": "Reflects if this user is an admin of the workspace." }, "is_guest": { "type": "boolean", "readOnly": true, "description": "Reflects if this user is a guest of the workspace." }, "is_view_only": { "type": "boolean", "readOnly": true, "description": "Reflects if this user has view only license in the workspace." }, "vacation_dates": { "type": "object", "readOnly": true, "nullable": true, "description": "Contains keys `start_on` and `end_on` for the vacation dates for the user in this workspace. If `start_on` is null, the entire `vacation_dates` object will be null. If `end_on` is before today, the entire `vacation_dates` object will be null.", "properties": { "start_on": { "description": "The day on which the user's vacation in this workspace starts. This is a date with `YYYY-MM-DD` format.", "type": "string", "example": "2022-11-05" }, "end_on": { "description": "The day on which the user's vacation in this workspace ends, or null if there is no end date. This is a date with `YYYY-MM-DD` format.", "nullable": true, "type": "string", "example": "2022-11-07" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, "WorkspaceRemoveUserRequest": { "type": "object", "description": "A user identification object for specification with the addUser/removeUser endpoints.", "properties": { "user": { "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "12345" } } }, "WorkspaceRequest": { "$ref": "#/components/schemas/WorkspaceBase" }, "WorkspaceResponse": { "allOf": [ { "$ref": "#/components/schemas/WorkspaceBase" }, { "type": "object", "properties": { "email_domains": { "description": "The email domains that are associated with this workspace.", "type": "array", "items": { "type": "string", "format": "uri" }, "example": [ "asana.com" ] }, "is_organization": { "description": "Whether the workspace is an *organization*.", "type": "boolean", "example": false } } } ] }, "GoalMembershipBase": { "description": "This object represents a user's connection to a goal.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "membership" }, "resource_subtype": { "type": "string", "readOnly": true, "description": "The type of membership.", "example": "goal_membership" }, "member": { "$ref": "#/components/schemas/MemberCompact" }, "parent": { "allOf": [ { "$ref": "#/components/schemas/GoalCompact" }, { "type": "object", "readOnly": true } ] }, "role": { "type": "string", "description": "*Deprecated: Describes if the member is a commenter or editor in goal.*", "enum": [ "commenter", "editor" ], "deprecated": true, "example": "editor" }, "access_level": { "type": "string", "description": "\"Describes the membership access level for the goal. (`admin` and `viewer` are currently only available when you include the header: `Asana-Enable: goal_sals_api`.) This is preferred over role.\"", "enum": [ "viewer", "commenter", "editor", "admin" ], "example": "editor" }, "goal": { "allOf": [ { "$ref": "#/components/schemas/GoalCompact" }, { "type": "object", "readOnly": true, "deprecated": true, "description": "*Deprecated: new integrations should prefer the `parent` field.* A *Goal* is an object in the goal-tracking system that helps your organization drive measurable results." } ] } } }, "GoalMembershipCompact": { "allOf": [ { "$ref": "#/components/schemas/GoalMembershipBase" }, { "type": "object", "properties": { "is_commenter": { "type": "boolean", "deprecated": true, "readOnly": true, "description": "*Deprecated: new integrations should prefer the `role` field.* Describes if the member is comment only in goal. Will be null if the `goal_sals_api` change flag is enabled.", "example": false }, "is_editor": { "type": "boolean", "deprecated": true, "readOnly": true, "description": "*Deprecated: new integrations should prefer the `role` field.* Describes if the member is editor in goal. Will be null if the `goal_sals_api` change flag is enabled.", "example": false } } } ] }, "GoalMembershipResponse": { "allOf": [ { "$ref": "#/components/schemas/GoalMembershipBase" }, { "type": "object", "properties": { "user": { "allOf": [ { "$ref": "#/components/schemas/UserCompact" }, { "type": "object", "deprecated": true, "readOnly": true, "description": "*Deprecated: new integrations should prefer the `member` field.* A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks." } ] }, "workspace": { "allOf": [ { "$ref": "#/components/schemas/WorkspaceCompact" }, { "type": "object", "deprecated": true, "readOnly": true, "description": "*Deprecated:* A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace." } ] } } } ] }, "MembershipUpdateRequest": { "type": "object", "properties": { "access_level": { "description": "The role given to the member. Goals can have access levels `editor` or `commenter`. Projects can have access levels `admin`, `editor` or `commenter`. Portfolios can have access levels `admin`, `editor` or `viewer`.", "type": "string", "example": "editor" } } }, "MembershipRequest": { "type": "object", "properties": { "access_level": { "description": "Sets the access level for the member. Goals can have access levels `viewer`, `commenter`, `editor` or `admin` (`viewer` and `admin` are currently only available for Goals when you include the `Asana-Enable: goal_sals_api` change flag header). Projects can have access levels `admin`, `editor` or `commenter`. Portfolios can have access levels `admin`, `editor` or `viewer`. Custom Fields can have access levels `admin`, `editor` or `user`.", "type": "string", "example": "editor" } } }, "CreateMembershipRequest": { "allOf": [ { "$ref": "#/components/schemas/MembershipRequest" }, { "type": "object", "properties": { "member": { "description": "The gid of the user or team.", "type": "string", "example": 12345 }, "parent": { "description": "The gid of the `goal`, `project`, or `portfolio` to add the member to.", "type": "string", "example": "987654" }, "role": { "description": "*Deprecated: new integrations should use access_level* The role given to the member. Optional argument, will default to `commenter` for goals and the default project role for projects. Can be `editor` or `commenter` for goals. Can be `admin`,`editor` or `commenter` for projects.", "type": "string", "deprecated": true, "example": "editor" } } } ] }, "MembershipResponse": { "anyOf": [ { "$ref": "#/components/schemas/GoalMembershipResponse" }, { "$ref": "#/components/schemas/ProjectMembershipCompactResponse" }, { "$ref": "#/components/schemas/PortfolioMembershipResponse" }, { "$ref": "#/components/schemas/CustomFieldMembershipResponse" } ] }, "UpdateTimeTrackingEntryRequest": { "type": "object", "properties": { "duration_minutes": { "description": "*Optional*. Time in minutes tracked by the entry", "type": "integer", "example": 12 }, "entered_on": { "description": "*Optional*. The day that this entry is logged on. Defaults to today if no day specified", "type": "string", "format": "date", "example": "2023-03-19" }, "attributable_to": { "type": "string", "description": "*Optional*. The gid of the project which the time is attributable to.", "example": "987654" } } }, "CreateTimeTrackingEntryRequest": { "type": "object", "properties": { "duration_minutes": { "description": "Time in minutes tracked by the entry. Must be greater than 0", "type": "integer", "example": 12 }, "entered_on": { "description": "*Optional*. The day that this entry is logged on. Defaults to today if not specified", "type": "string", "format": "date", "example": "2023-03-19" }, "attributable_to": { "type": "string", "description": "*Optional*. The gid of the project which the time is attributable to.", "example": "987654" } } }, "TimeTrackingEntryCompact": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_tracking_entry", "x-insert-after": "gid" }, "duration_minutes": { "description": "Time in minutes tracked by the entry.", "type": "integer", "example": 12 }, "entered_on": { "description": "The day that this entry is logged on.", "type": "string", "format": "date", "example": "2015-03-14" }, "attributable_to": { "allOf": [ { "$ref": "#/components/schemas/ProjectCompact" }, { "type": "object", "description": "The attributable to project specifies which project's budget a time entry should be counted toward, if the task belongs to more than one project. If it only belongs to one project, it should be that project." } ] }, "created_by": { "$ref": "#/components/schemas/UserCompact", "readOnly": true } } }, "TimeTrackingEntryBase": { "allOf": [ { "$ref": "#/components/schemas/TimeTrackingEntryCompact" }, { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/TaskCompact", "readOnly": true }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "approval_status": { "description": "*Optional*. The current approval status of the entry.", "type": "string", "readOnly": true, "enum": [ "DRAFT", "SUBMITTED", "APPROVED", "REJECTED" ], "example": "DRAFT" }, "billable_status": { "description": "*Optional*. The current billable status of the entry.", "type": "string", "readOnly": true, "enum": [ "billable", "nonBillable", "notApplicable" ], "example": "billable" }, "description": { "description": "*Optional*. The description of the entry.", "type": "string", "readOnly": true, "example": "My description of work done on this entry" } } } ] }, "AccessRequestResponse": { "description": "A *access request* object represents a request to access a shareable resource within Asana. It includes the requester's information, approval status, and target resource details.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "access_request", "x-insert-after": "gid" }, "message": { "description": "The message included in the access request, if any.", "type": "string", "example": "Please grant me access to this resource." }, "approval_status": { "description": "The current approval status of the request.", "type": "string", "enum": [ "pending", "approved", "denied" ], "example": "pending" }, "requester": { "$ref": "#/components/schemas/UserCompact", "description": "The user who made the access request.", "readOnly": true }, "target": { "$ref": "#/components/schemas/AccessRequestTargetIdCompact", "description": "The target resource that the requester wants access to.", "readOnly": true } } }, "AccessRequestTargetIdCompact": { "description": "A *target id* object represents the target resource that the requester wants access to.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" } } }, "AccessRequestCreateRequest": { "type": "object", "required": [ "target" ], "description": "A request to create shareable access for a user.", "properties": { "target": { "description": "The access requestable object that the user is requesting access to. This is the gid of the target. Supports projects and portfolios.", "type": "string", "example": "12345" }, "message": { "type": "string", "description": "The optional message to include with the access request. This can be used to provide context or additional information about the request.", "example": "I'm looking to request access to this item.", "nullable": true } } }, "AccessRequestApproveRequest": { "type": "object", "description": "A request to approve access for a user.", "properties": { "access_request_gid": { "description": "The ID of the access request that the user is approving.", "type": "string", "example": "12345" } } }, "AccessRequestRejectRequest": { "type": "object", "description": "A request to reject access for a user.", "properties": { "access_request_gid": { "description": "The ID of the access request that the user is rejecting.", "type": "string", "example": "12345" } } }, "ReactionCompact": { "type": "object", "description": "An emoji reaction on an object.", "properties": { "gid": { "description": "The ID of the reaction object.", "type": "string", "example": "12345" }, "emoji": { "description": "The emoji string used in the reaction.", "type": "string", "example": "\ud83d\udc4d" }, "user": { "$ref": "#/components/schemas/UserCompact", "readOnly": true } } }, "ReactionSummaryItemCompact": { "type": "object", "description": "A summary of an emoji reaction on an object.", "properties": { "emoji_base": { "description": "The emoji base character used in the reaction.", "type": "string", "example": "\ud83d\udc4e" }, "variant": { "description": "The full emoji string used in the reaction.", "type": "string", "example": "\ud83d\udc4e\ud83c\udffc" }, "count": { "description": "The number of reactions with the emoji variant on the object.", "type": "number", "example": 1 }, "reacted": { "description": "Whether the current user has reacted with the emoji variant on the object.", "type": "boolean", "example": false } } } }, "securitySchemes": { "personalAccessToken": { "type": "http", "description": "A personal access token allows access to the api for the user who created it. This should be kept a secret and be treated like a password.", "scheme": "bearer" }, "oauth2": { "type": "oauth2", "description": "We require that applications designed to access the Asana API on behalf of multiple users implement OAuth 2.0.\nAsana supports the Authorization Code Grant flow.", "flows": { "authorizationCode": { "authorizationUrl": "https://app.asana.com/-/oauth_authorize", "tokenUrl": "https://app.asana.com/-/oauth_token", "refreshUrl": "https://app.asana.com/-/oauth_token", "scopes": { "default": "Provides access to all endpoints documented in our API reference. If no scopes are requested, this scope is assumed by default.", "openid": "Provides access to OpenID Connect ID tokens and the OpenID Connect user info endpoint.", "email": "Provides access to the user\u2019s email through the OpenID Connect user info endpoint.", "profile": "Provides access to the user\u2019s name and profile photo through the OpenID Connect user info endpoint.", "attachments:read": "View access to attachments", "attachments:write": "Create and modify access to attachments", "attachments:delete": "Delete access to attachments", "custom_fields:read": "View access to custom fields", "custom_fields:write": "Create and modify access to custom fields", "goals:read": "View access to goals", "tasks:read": "View access to tasks", "tasks:write": "Create and modify access to tasks", "tasks:delete": "Delete access to tasks", "task_custom_types:read": "View access to task custom types", "task_templates:read": "View access to task templates", "team_memberships:read": "View access to team memberships", "portfolios:read": "View access to portfolios", "portfolios:write": "Create and modify access to portfolios", "project_templates:read": "View access to project templates", "projects:delete": "Delete access to projects", "projects:read": "View access to projects", "projects:write": "Create and modify access to projects", "users:read": "View access to users", "teams:read": "View access to teams", "time_tracking_entries:read": "View access to time tracking entries", "stories:read": "View access to stories", "stories:write": "Create and modify access to stories", "tags:read": "View access to tags", "tags:write": "Create and modify access to tags", "webhooks:read": "View access to webhooks", "webhooks:write": "Create and modify access to webhooks", "webhooks:delete": "Delete access to webhooks", "workspaces:read": "View access to workspaces" } } } } } }, "paths": { "/access_requests": { "get": { "summary": "Get access requests", "description": "Returns the pending access requests for a target object or a target object filtered by user.", "tags": [ "Access requests" ], "operationId": "getAccessRequests", "parameters": [ { "name": "target", "in": "query", "description": "Globally unique identifier for the target object.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "target" }, { "name": "user", "in": "query", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "approval_status", "message", "requester", "requester.name", "target" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "approval_status", "message", "requester", "requester.name", "target" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved access requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *access request* object represents a request to access a shareable resource within Asana. It includes the requester's information, approval status, and target resource details.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "access_request", "x-insert-after": "gid" }, "message": { "description": "The message included in the access request, if any.", "type": "string", "example": "Please grant me access to this resource." }, "approval_status": { "description": "The current approval status of the request.", "type": "string", "enum": [ "pending", "approved", "denied" ], "example": "pending" }, "requester": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "target": { "description": "A *target id* object represents the target resource that the requester wants access to.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet accessRequestsApiInstance = new Asana.AccessRequestsApi();\nlet target = \"1331\"; // String | Globally unique identifier for the target object.\nlet opts = { \n 'user': \"me\", \n 'opt_fields': \"approval_status,message,requester,requester.name,target\"\n};\naccessRequestsApiInstance.getAccessRequests(target, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\naccess_requests_api_instance = asana.AccessRequestsApi(api_client)\ntarget = \"1331\" # str | Globally unique identifier for the target object.\nopts = {\n 'user': \"me\", # str | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\n 'opt_fields': \"approval_status,message,requester,requester.name,target\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get access requests\n api_response = access_requests_api_instance.get_access_requests(target, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling AccessRequestsApi->get_access_requests: %s\\n\" % e)", "name": "python-sdk-v5" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create an access request", "description": "Submits a new access request for a private object. Currently supports projects and portfolios.", "operationId": "createAccessRequest", "tags": [ "Access requests" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "target" ], "description": "A request to create shareable access for a user.", "properties": { "target": { "description": "The access requestable object that the user is requesting access to. This is the gid of the target. Supports projects and portfolios.", "type": "string", "example": "12345" }, "message": { "type": "string", "description": "The optional message to include with the access request. This can be used to provide context or additional information about the request.", "example": "I'm looking to request access to this item.", "nullable": true } } } } } } } }, "responses": { "201": { "description": "Successfully created a new access request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A *access request* object represents a request to access a shareable resource within Asana. It includes the requester's information, approval status, and target resource details.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "access_request", "x-insert-after": "gid" }, "message": { "description": "The message included in the access request, if any.", "type": "string", "example": "Please grant me access to this resource." }, "approval_status": { "description": "The current approval status of the request.", "type": "string", "enum": [ "pending", "approved", "denied" ], "example": "pending" }, "requester": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "target": { "description": "A *target id* object represents the target resource that the requester wants access to.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet accessRequestsApiInstance = new Asana.AccessRequestsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | \n\naccessRequestsApiInstance.createAccessRequest(body).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\naccess_requests_api_instance = asana.AccessRequestsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | \n\n\ntry:\n # Create an access request\n api_response = access_requests_api_instance.create_access_request(body)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling AccessRequestsApi->create_access_request: %s\\n\" % e)", "name": "python-sdk-v5" } ] }, "x-moar-primitive-count": 2, "x-moar-complexity-skipped": false } }, "/access_requests/{access_request_gid}/approve": { "post": { "summary": "Approve an access request", "description": "Approves an access request for a target object.", "tags": [ "Access requests" ], "operationId": "approveAccessRequest", "parameters": [ { "name": "access_request_gid", "in": "path", "description": "Globally unique identifier for the access request.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "access_request" } ], "responses": { "200": { "description": "Successfully approved an access request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet accessRequestsApiInstance = new Asana.AccessRequestsApi();\nlet access_request_gid = \"12345\"; // String | Globally unique identifier for the access request.\n\naccessRequestsApiInstance.approveAccessRequest(access_request_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\naccess_requests_api_instance = asana.AccessRequestsApi(api_client)\naccess_request_gid = \"12345\" # str | Globally unique identifier for the access request.\n\n\ntry:\n # Approve an access request\n api_response = access_requests_api_instance.approve_access_request(access_request_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling AccessRequestsApi->approve_access_request: %s\\n\" % e)", "name": "python-sdk-v5" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/access_requests/{access_request_gid}/reject": { "post": { "summary": "Reject an access request", "description": "Rejects an access request for a target object.", "tags": [ "Access requests" ], "operationId": "rejectAccessRequest", "parameters": [ { "name": "access_request_gid", "in": "path", "description": "Globally unique identifier for the access request.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "access_request" } ], "responses": { "200": { "description": "Successfully rejected an access request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet accessRequestsApiInstance = new Asana.AccessRequestsApi();\nlet access_request_gid = \"12345\"; // String | Globally unique identifier for the access request.\n\naccessRequestsApiInstance.rejectAccessRequest(access_request_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\naccess_requests_api_instance = asana.AccessRequestsApi(api_client)\naccess_request_gid = \"12345\" # str | Globally unique identifier for the access request.\n\n\ntry:\n # Reject an access request\n api_response = access_requests_api_instance.reject_access_request(access_request_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling AccessRequestsApi->reject_access_request: %s\\n\" % e)", "name": "python-sdk-v5" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/allocations/{allocation_gid}": { "parameters": [ { "name": "allocation_gid", "in": "path", "description": "Globally unique identifier for the allocation.", "required": true, "schema": { "type": "string" }, "example": "77688", "x-env-variable": "allocation" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get an allocation", "description": "Returns the complete allocation record for a single allocation.", "tags": [ "Allocations" ], "operationId": "getAllocation", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "assignee", "assignee.name", "created_by", "created_by.name", "effort", "effort.type", "effort.value", "end_date", "parent", "parent.name", "resource_subtype", "start_date" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "assignee", "assignee.name", "created_by", "created_by.name", "effort", "effort.type", "effort.value", "end_date", "parent", "parent.name", "resource_subtype", "start_date" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the record for a single allocation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "allocation", "x-insert-after": "gid" }, "start_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation starts.", "example": "2024-02-28" }, "end_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation ends.", "example": "2024-02-28" }, "effort": { "type": "object", "nullable": true, "description": "The amount of time associated with the allocation, represented as a percentage or number of hours", "properties": { "type": { "type": "string", "description": "The units used for tracking effort on an allocation, either \"hours\" or \"percent\".", "enum": [ "hours", "percent" ] }, "value": { "type": "number", "description": "The numeric effort value on the allocation.", "example": 50 } } } } }, { "type": "object", "properties": { "assignee": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "description": "The user or placeholder assigned to the allocation.", "properties": { "name": { "type": "string", "description": "The name of allocation resource.", "example": "Greg Sanchez" } } } ] }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "parent": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "resource_subtype": { "description": "The subtype of the allocation.", "type": "string", "example": "project_allocation" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet allocationsApiInstance = new Asana.AllocationsApi();\nlet allocation_gid = \"77688\"; // String | Globally unique identifier for the allocation.\nlet opts = { \n 'opt_fields': \"assignee,assignee.name,created_by,created_by.name,effort,effort.type,effort.value,end_date,parent,parent.name,resource_subtype,start_date\"\n};\nallocationsApiInstance.getAllocation(allocation_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.allocations.getAllocation(allocationGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nallocations_api_instance = asana.AllocationsApi(api_client)\nallocation_gid = \"77688\" # str | Globally unique identifier for the allocation.\nopts = {\n 'opt_fields': \"assignee,assignee.name,created_by,created_by.name,effort,effort.type,effort.value,end_date,parent,parent.name,resource_subtype,start_date\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get an allocation\n api_response = allocations_api_instance.get_allocation(allocation_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling AllocationsApi->get_allocation: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.allocations.get_allocation(allocation_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update an allocation", "description": "An existing allocation can be updated by making a PUT request on the URL for\nthat allocation. Only the fields provided in the `data` block will be updated;\nany unspecified fields will remain unchanged.\n\nReturns the complete updated allocation record.", "tags": [ "Allocations" ], "operationId": "updateAllocation", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "assignee", "assignee.name", "created_by", "created_by.name", "effort", "effort.type", "effort.value", "end_date", "parent", "parent.name", "resource_subtype", "start_date" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "assignee", "assignee.name", "created_by", "created_by.name", "effort", "effort.type", "effort.value", "end_date", "parent", "parent.name", "resource_subtype", "start_date" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The updated fields for the allocation.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "allocation", "x-insert-after": "gid" }, "start_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation starts.", "example": "2024-02-28" }, "end_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation ends.", "example": "2024-02-28" }, "effort": { "type": "object", "nullable": true, "description": "The amount of time associated with the allocation, represented as a percentage or number of hours", "properties": { "type": { "type": "string", "description": "The units used for tracking effort on an allocation, either \"hours\" or \"percent\".", "enum": [ "hours", "percent" ] }, "value": { "type": "number", "description": "The numeric effort value on the allocation.", "example": 50 } } } } }, { "type": "object", "properties": { "assignee": { "type": "string", "description": "Globally unique identifier for the user or placeholder assigned to the allocation." }, "parent": { "type": "string", "description": "Globally unique identifier for the project the allocation is on." } } } ] } } } } } }, "responses": { "200": { "description": "Successfully updated the allocation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "allocation", "x-insert-after": "gid" }, "start_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation starts.", "example": "2024-02-28" }, "end_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation ends.", "example": "2024-02-28" }, "effort": { "type": "object", "nullable": true, "description": "The amount of time associated with the allocation, represented as a percentage or number of hours", "properties": { "type": { "type": "string", "description": "The units used for tracking effort on an allocation, either \"hours\" or \"percent\".", "enum": [ "hours", "percent" ] }, "value": { "type": "number", "description": "The numeric effort value on the allocation.", "example": 50 } } } } }, { "type": "object", "properties": { "assignee": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "description": "The user or placeholder assigned to the allocation.", "properties": { "name": { "type": "string", "description": "The name of allocation resource.", "example": "Greg Sanchez" } } } ] }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "parent": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "resource_subtype": { "description": "The subtype of the allocation.", "type": "string", "example": "project_allocation" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet allocationsApiInstance = new Asana.AllocationsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The updated fields for the allocation.\nlet allocation_gid = \"77688\"; // String | Globally unique identifier for the allocation.\nlet opts = { \n 'opt_fields': \"assignee,assignee.name,created_by,created_by.name,effort,effort.type,effort.value,end_date,parent,parent.name,resource_subtype,start_date\"\n};\nallocationsApiInstance.updateAllocation(body, allocation_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.allocations.updateAllocation(allocationGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nallocations_api_instance = asana.AllocationsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The updated fields for the allocation.\nallocation_gid = \"77688\" # str | Globally unique identifier for the allocation.\nopts = {\n 'opt_fields': \"assignee,assignee.name,created_by,created_by.name,effort,effort.type,effort.value,end_date,parent,parent.name,resource_subtype,start_date\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update an allocation\n api_response = allocations_api_instance.update_allocation(body, allocation_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling AllocationsApi->update_allocation: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.allocations.update_allocation(allocation_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 8, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete an allocation", "description": "A specific, existing allocation can be deleted by making a DELETE request on the URL for that allocation.\n\nReturns an empty data record.", "tags": [ "Allocations" ], "operationId": "deleteAllocation", "responses": { "200": { "description": "Successfully deleted the specified allocation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet allocationsApiInstance = new Asana.AllocationsApi();\nlet allocation_gid = \"77688\"; // String | Globally unique identifier for the allocation.\n\nallocationsApiInstance.deleteAllocation(allocation_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.allocations.deleteAllocation(allocationGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nallocations_api_instance = asana.AllocationsApi(api_client)\nallocation_gid = \"77688\" # str | Globally unique identifier for the allocation.\n\n\ntry:\n # Delete an allocation\n api_response = allocations_api_instance.delete_allocation(allocation_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling AllocationsApi->delete_allocation: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.allocations.delete_allocation(allocation_gid, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/allocations": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get multiple allocations", "description": "Returns a list of allocations filtered to a specific project, user or placeholder.", "tags": [ "Allocations" ], "operationId": "getAllocations", "parameters": [ { "name": "parent", "in": "query", "description": "Globally unique identifier for the project to filter allocations by.", "schema": { "type": "string" }, "example": "77688" }, { "name": "assignee", "in": "query", "description": "Globally unique identifier for the user or placeholder the allocation is assigned to.", "schema": { "type": "string" }, "example": "12345" }, { "name": "workspace", "in": "query", "description": "Globally unique identifier for the workspace.", "schema": { "type": "string" }, "example": "98765" }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "assignee", "assignee.name", "created_by", "created_by.name", "effort", "effort.type", "effort.value", "end_date", "offset", "parent", "parent.name", "path", "resource_subtype", "start_date", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "assignee", "assignee.name", "created_by", "created_by.name", "effort", "effort.type", "effort.value", "end_date", "offset", "parent", "parent.name", "path", "resource_subtype", "start_date", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested allocations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "allocation", "x-insert-after": "gid" }, "start_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation starts.", "example": "2024-02-28" }, "end_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation ends.", "example": "2024-02-28" }, "effort": { "type": "object", "nullable": true, "description": "The amount of time associated with the allocation, represented as a percentage or number of hours", "properties": { "type": { "type": "string", "description": "The units used for tracking effort on an allocation, either \"hours\" or \"percent\".", "enum": [ "hours", "percent" ] }, "value": { "type": "number", "description": "The numeric effort value on the allocation.", "example": 50 } } } } }, { "type": "object", "properties": { "assignee": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "description": "The user or placeholder assigned to the allocation.", "properties": { "name": { "type": "string", "description": "The name of allocation resource.", "example": "Greg Sanchez" } } } ] }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "parent": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "resource_subtype": { "description": "The subtype of the allocation.", "type": "string", "example": "project_allocation" } } } ] } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet allocationsApiInstance = new Asana.AllocationsApi();\nlet opts = { \n 'parent': \"77688\", \n 'assignee': \"12345\", \n 'workspace': \"98765\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"assignee,assignee.name,created_by,created_by.name,effort,effort.type,effort.value,end_date,offset,parent,parent.name,path,resource_subtype,start_date,uri\"\n};\nallocationsApiInstance.getAllocations(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.allocations.getAllocations({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nallocations_api_instance = asana.AllocationsApi(api_client)\nopts = {\n 'parent': \"77688\", # str | Globally unique identifier for the project to filter allocations by.\n 'assignee': \"12345\", # str | Globally unique identifier for the user or placeholder the allocation is assigned to.\n 'workspace': \"98765\", # str | Globally unique identifier for the workspace.\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"assignee,assignee.name,created_by,created_by.name,effort,effort.type,effort.value,end_date,offset,parent,parent.name,path,resource_subtype,start_date,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple allocations\n api_response = allocations_api_instance.get_allocations(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling AllocationsApi->get_allocations: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.allocations.get_allocations({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create an allocation", "description": "Creates a new allocation.\n\nReturns the full record of the newly created allocation.", "tags": [ "Allocations" ], "operationId": "createAllocation", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "assignee", "assignee.name", "created_by", "created_by.name", "effort", "effort.type", "effort.value", "end_date", "parent", "parent.name", "resource_subtype", "start_date" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "assignee", "assignee.name", "created_by", "created_by.name", "effort", "effort.type", "effort.value", "end_date", "parent", "parent.name", "resource_subtype", "start_date" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The allocation to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "allocation", "x-insert-after": "gid" }, "start_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation starts.", "example": "2024-02-28" }, "end_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation ends.", "example": "2024-02-28" }, "effort": { "type": "object", "nullable": true, "description": "The amount of time associated with the allocation, represented as a percentage or number of hours", "properties": { "type": { "type": "string", "description": "The units used for tracking effort on an allocation, either \"hours\" or \"percent\".", "enum": [ "hours", "percent" ] }, "value": { "type": "number", "description": "The numeric effort value on the allocation.", "example": 50 } } } } }, { "type": "object", "properties": { "assignee": { "type": "string", "description": "Globally unique identifier for the user or placeholder assigned to the allocation." }, "parent": { "type": "string", "description": "Globally unique identifier for the project the allocation is on." } } } ] }, { "type": "object", "required": [ "assignee", "end_date", "parent", "start_date" ] } ] } } } } } }, "responses": { "201": { "description": "Successfully created a new allocation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "allocation", "x-insert-after": "gid" }, "start_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation starts.", "example": "2024-02-28" }, "end_date": { "type": "string", "format": "date", "description": "The localized day on which the allocation ends.", "example": "2024-02-28" }, "effort": { "type": "object", "nullable": true, "description": "The amount of time associated with the allocation, represented as a percentage or number of hours", "properties": { "type": { "type": "string", "description": "The units used for tracking effort on an allocation, either \"hours\" or \"percent\".", "enum": [ "hours", "percent" ] }, "value": { "type": "number", "description": "The numeric effort value on the allocation.", "example": 50 } } } } }, { "type": "object", "properties": { "assignee": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "description": "The user or placeholder assigned to the allocation.", "properties": { "name": { "type": "string", "description": "The name of allocation resource.", "example": "Greg Sanchez" } } } ] }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "parent": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "resource_subtype": { "description": "The subtype of the allocation.", "type": "string", "example": "project_allocation" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet allocationsApiInstance = new Asana.AllocationsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The allocation to create.\nlet opts = { \n 'opt_fields': \"assignee,assignee.name,created_by,created_by.name,effort,effort.type,effort.value,end_date,parent,parent.name,resource_subtype,start_date\"\n};\nallocationsApiInstance.createAllocation(body, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.allocations.createAllocation({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nallocations_api_instance = asana.AllocationsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The allocation to create.\nopts = {\n 'opt_fields': \"assignee,assignee.name,created_by,created_by.name,effort,effort.type,effort.value,end_date,parent,parent.name,resource_subtype,start_date\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create an allocation\n api_response = allocations_api_instance.create_allocation(body, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling AllocationsApi->create_allocation: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.allocations.create_allocation({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 8, "x-moar-complexity-skipped": false } }, "/attachments/{attachment_gid}": { "parameters": [ { "name": "attachment_gid", "in": "path", "description": "Globally unique identifier for the attachment.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "attachment" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get an attachment", "description": "Required scope: attachments:read\n\nGet the full record for a single attachment.", "tags": [ "Attachments" ], "operationId": "getAttachment", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "connected_to_app", "created_at", "download_url", "host", "name", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permanent_url", "resource_subtype", "size", "view_url" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "connected_to_app", "created_at", "download_url", "host", "name", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permanent_url", "resource_subtype", "size", "view_url" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the record for a single attachment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "An *attachment* object represents any file attached to a task in Asana, whether it's an uploaded file or one associated via a third-party service such as Dropbox or Google Drive.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "attachment", "x-insert-after": "gid" }, "name": { "description": "The name of the file.", "type": "string", "readOnly": true, "example": "Screenshot.png" }, "resource_subtype": { "description": "The service hosting the attachment. Valid values are `asana`, `dropbox`, `gdrive`, `onedrive`, `box`, `vimeo`, and `external`.", "type": "string", "example": "dropbox" } } }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "The URL containing the content of the attachment.\n*Note:* May be null if the attachment is hosted by [Box](https://www.box.com/) and will be null if the attachment is a Video Message hosted by [Vimeo](https://vimeo.com/). If present, this URL may only be valid for two minutes from the time of retrieval. You should avoid persisting this URL somewhere and just refresh it on demand to ensure you do not keep stale URLs.", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://s3.amazonaws.com/assets/123/Screenshot.png" }, "permanent_url": { "description": "A stable URL for accessing the attachment through the Asana web application. This URL redirects to the file download location (e.g., an S3 link) if the user is authenticated and authorized to view the parent object (e.g., a task). Unauthorized users will receive a `403 Forbidden` response. This link is persistent and does not expire, but requires an active session to resolve.", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://app.asana.com/app/asana/-/get_asset?asset_id=1234567890" }, "host": { "description": "The service hosting the attachment. Valid values are `asana`, `dropbox`, `gdrive`, `box`, and `vimeo`.", "type": "string", "readOnly": true, "example": "dropbox" }, "parent": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "nullable": true, "description": "The task this attachment is attached to.", "readOnly": true, "properties": { "resource_subtype": { "description": "The resource subtype of the parent resource that the filter applies to.", "type": "string", "example": "default_task", "nullable": true } } } ] }, "size": { "description": "The size of the attachment in bytes. Only present when the `resource_subtype` is `asana`.", "type": "integer", "readOnly": true, "example": 12345 }, "view_url": { "description": "The URL where the attachment can be viewed, which may be friendlier to users in a browser than just directing them to a raw file. May be null if no view URL exists for the service.", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://www.dropbox.com/s/123/Screenshot.png" }, "connected_to_app": { "description": "Whether the attachment is connected to the app making the request for the purposes of showing an app components widget. Only present when the `resource_subtype` is `external` or `gdrive`.", "type": "boolean", "readOnly": true } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "424": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "501": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } }, "security": [ { "oauth2": [ "attachments:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nAttachment result = client.attachments.getAttachment(attachmentGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet attachmentsApiInstance = new Asana.AttachmentsApi();\nlet attachment_gid = \"12345\"; // String | Globally unique identifier for the attachment.\nlet opts = { \n 'opt_fields': \"connected_to_app,created_at,download_url,host,name,parent,parent.created_by,parent.name,parent.resource_subtype,permanent_url,resource_subtype,size,view_url\"\n};\nattachmentsApiInstance.getAttachment(attachment_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.attachments.getAttachment(attachmentGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nattachments_api_instance = asana.AttachmentsApi(api_client)\nattachment_gid = \"12345\" # str | Globally unique identifier for the attachment.\nopts = {\n 'opt_fields': \"connected_to_app,created_at,download_url,host,name,parent,parent.created_by,parent.name,parent.resource_subtype,permanent_url,resource_subtype,size,view_url\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get an attachment\n api_response = attachments_api_instance.get_attachment(attachment_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling AttachmentsApi->get_attachment: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.attachments.get_attachment(attachment_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "attachments->getAttachment($attachment_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.attachments.get_attachment(attachment_gid: 'attachment_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete an attachment", "description": "Required scope: attachments:delete\n\nDeletes a specific, existing attachment.\n\nReturns an empty data record.", "tags": [ "Attachments" ], "operationId": "deleteAttachment", "responses": { "200": { "description": "Successfully deleted the specified attachment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "attachments:delete" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.attachments.deleteAttachment(attachmentGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet attachmentsApiInstance = new Asana.AttachmentsApi();\nlet attachment_gid = \"12345\"; // String | Globally unique identifier for the attachment.\n\nattachmentsApiInstance.deleteAttachment(attachment_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.attachments.deleteAttachment(attachmentGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nattachments_api_instance = asana.AttachmentsApi(api_client)\nattachment_gid = \"12345\" # str | Globally unique identifier for the attachment.\n\n\ntry:\n # Delete an attachment\n api_response = attachments_api_instance.delete_attachment(attachment_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling AttachmentsApi->delete_attachment: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.attachments.delete_attachment(attachment_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "attachments->deleteAttachment($attachment_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.attachments.delete_attachment(attachment_gid: 'attachment_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/attachments": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get attachments from an object", "description": "Required scope: attachments:read\n\nReturns the compact records for all attachments on the object.\nThere are three possible `parent` values for this request: `project`, `project_brief`, and `task`. For a project, an attachment refers to a file uploaded to the \"Key resources\" section in the project Overview. For a project brief, an attachment refers to inline files in the project brief itself. For a task, an attachment refers to a file directly associated to that task.\n\nNote that within the Asana app, inline images in the task description do not appear in the index of image thumbnails nor as stories in the task. However, requests made to `GET /attachments` for a task will return all of the images in the task, including inline images.", "tags": [ "Attachments" ], "operationId": "getAttachmentsForObject", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "parent", "required": true, "in": "query", "description": "Globally unique identifier for object to fetch statuses from. Must be a GID for a `project`, `project_brief`, or `task`.", "schema": { "type": "string" }, "example": "159874" }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "connected_to_app", "created_at", "download_url", "host", "name", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permanent_url", "resource_subtype", "size", "uri", "view_url" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "connected_to_app", "created_at", "download_url", "host", "name", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permanent_url", "resource_subtype", "size", "uri", "view_url" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified object's attachments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "An *attachment* object represents any file attached to a task in Asana, whether it's an uploaded file or one associated via a third-party service such as Dropbox or Google Drive.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "attachment", "x-insert-after": "gid" }, "name": { "description": "The name of the file.", "type": "string", "readOnly": true, "example": "Screenshot.png" }, "resource_subtype": { "description": "The service hosting the attachment. Valid values are `asana`, `dropbox`, `gdrive`, `onedrive`, `box`, `vimeo`, and `external`.", "type": "string", "example": "dropbox" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "attachments:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.attachments.getAttachmentsForObject(parent)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet attachmentsApiInstance = new Asana.AttachmentsApi();\nlet parent = \"159874\"; // String | Globally unique identifier for object to fetch statuses from. Must be a GID for a `project`, `project_brief`, or `task`.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"connected_to_app,created_at,download_url,host,name,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permanent_url,resource_subtype,size,uri,view_url\"\n};\nattachmentsApiInstance.getAttachmentsForObject(parent, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.attachments.getAttachmentsForObject({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nattachments_api_instance = asana.AttachmentsApi(api_client)\nparent = \"159874\" # str | Globally unique identifier for object to fetch statuses from. Must be a GID for a `project`, `project_brief`, or `task`.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"connected_to_app,created_at,download_url,host,name,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permanent_url,resource_subtype,size,uri,view_url\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get attachments from an object\n api_response = attachments_api_instance.get_attachments_for_object(parent, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling AttachmentsApi->get_attachments_for_object: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.attachments.get_attachments_for_object({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "attachments->getAttachmentsForObject(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.attachments.get_attachments_for_object(parent: ''parent_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Upload an attachment", "description": "Required scope: attachments:write\n\nUpload an attachment.\n\nThis method uploads an attachment on an object and returns the compact\nrecord for the created attachment object. This is possible by either:\n\n- Providing the URL of the external resource being attached, or\n- Downloading the file content first and then uploading it as any other attachment. Note that it is not possible to attach\nfiles from third party services such as Dropbox, Box, Vimeo & Google Drive via the API\n\nThe 100MB size limit on attachments in Asana is enforced on this endpoint.\n\nThis endpoint expects a multipart/form-data encoded request containing the full contents of the file to be uploaded.\n\nRequests made should follow the HTTP/1.1 specification that line\nterminators are of the form `CRLF` or `\\r\\n` outlined\n[here](http://www.w3.org/Protocols/HTTP/1.1/draft-ietf-http-v11-spec-01#Basic-Rules) in order for the server to reliably and properly handle the request.\n\nFor file names that contain non-ASCII characters, the file name should be URL-encoded. For example, a file named `r\u00e9sum\u00e9.pdf` should be encoded as\n`r%C3%A9sum%C3%A9.pdf` and the `filename` parameter in the `Content-Disposition` header should be set to the encoded file name.\n\nBelow is an example of a cURL request with the `Content-Disposition` header:\n\n```\nexport ASANA_PAT=\"\"\nexport PARENT_ID=\"\"\nexport ENCODED_NAME=\"r%C3%A9sum%C3%A9.pdf\"\ncurl --location 'https://app.asana.com/api/1.0/attachments' \\\n --header 'Content-Type: multipart/form-data' \\\n --header 'Accept: application/json' \\\n --header \"Authorization: Bearer $ASANA_PAT\" \\\n --form \"parent=$PARENT_ID\" \\\n --form \"file=@/Users/exampleUser/Downloads/r\u00e9sum\u00e9.pdf;headers=\\\"Content-Disposition: form-data; name=\"file\"; filename=\"$ENCODED_NAME.pdf\"; filename*=UTF-8''$ENCODED_NAME.pdf\\\"\"\n```", "tags": [ "Attachments" ], "operationId": "createAttachmentForObject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "connected_to_app", "created_at", "download_url", "host", "name", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permanent_url", "resource_subtype", "size", "view_url" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "connected_to_app", "created_at", "download_url", "host", "name", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permanent_url", "resource_subtype", "size", "view_url" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The file you want to upload.\n\n*Note when using curl:*\n\nBe sure to add an `\u2018@\u2019` before the file path, and use the `--form`\noption instead of the `-d` option.\n\nWhen uploading PDFs with curl, force the content-type to be pdf by\nappending the content type to the file path: `--form\n\"file=@file.pdf;type=application/pdf\"`.", "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "parent" ], "properties": { "resource_subtype": { "description": "The type of the attachment. Must be one of the given values. If not specified, a file attachment of type `asana` will be assumed. Note that if the value of `resource_subtype` is `external`, a `parent`, `name`, and `url` must also be provided.\n", "type": "string", "example": "external", "enum": [ "asana", "dropbox", "gdrive", "onedrive", "box", "vimeo", "external" ] }, "file": { "description": "Required for `asana` attachments.\n", "type": "string", "format": "binary" }, "parent": { "description": "Required identifier of the parent task, project, or project_brief, as a string.\n", "type": "string" }, "url": { "description": "The URL of the external resource being attached. Required for attachments of type `external`.\n", "type": "string" }, "name": { "description": "The name of the external resource being attached. Required for attachments of type `external`.\n", "type": "string" }, "connect_to_app": { "description": "*Optional*. Only relevant for external attachments with a parent task.\nA boolean indicating whether the current app should be connected with\nthe attachment for the purposes of showing an app components widget.\nRequires the app to have been added to a project the parent task is in.\nThis property can only be set if an OAuth token is used to authenticate the request.\n\nCriteria for displaying app widget:\n1. An OAuth token must be used to authenticate the request\n2. The app needs to have its `widget_metadata_url` configured in the developer console\n3. The task the attachment is being attached to must be in a project with the app installed", "type": "boolean" } } } } } }, "responses": { "200": { "description": "Successfully uploaded the attachment to the parent object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "An *attachment* object represents any file attached to a task in Asana, whether it's an uploaded file or one associated via a third-party service such as Dropbox or Google Drive.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "attachment", "x-insert-after": "gid" }, "name": { "description": "The name of the file.", "type": "string", "readOnly": true, "example": "Screenshot.png" }, "resource_subtype": { "description": "The service hosting the attachment. Valid values are `asana`, `dropbox`, `gdrive`, `onedrive`, `box`, `vimeo`, and `external`.", "type": "string", "example": "dropbox" } } }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "The URL containing the content of the attachment.\n*Note:* May be null if the attachment is hosted by [Box](https://www.box.com/) and will be null if the attachment is a Video Message hosted by [Vimeo](https://vimeo.com/). If present, this URL may only be valid for two minutes from the time of retrieval. You should avoid persisting this URL somewhere and just refresh it on demand to ensure you do not keep stale URLs.", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://s3.amazonaws.com/assets/123/Screenshot.png" }, "permanent_url": { "description": "A stable URL for accessing the attachment through the Asana web application. This URL redirects to the file download location (e.g., an S3 link) if the user is authenticated and authorized to view the parent object (e.g., a task). Unauthorized users will receive a `403 Forbidden` response. This link is persistent and does not expire, but requires an active session to resolve.", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://app.asana.com/app/asana/-/get_asset?asset_id=1234567890" }, "host": { "description": "The service hosting the attachment. Valid values are `asana`, `dropbox`, `gdrive`, `box`, and `vimeo`.", "type": "string", "readOnly": true, "example": "dropbox" }, "parent": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "nullable": true, "description": "The task this attachment is attached to.", "readOnly": true, "properties": { "resource_subtype": { "description": "The resource subtype of the parent resource that the filter applies to.", "type": "string", "example": "default_task", "nullable": true } } } ] }, "size": { "description": "The size of the attachment in bytes. Only present when the `resource_subtype` is `asana`.", "type": "integer", "readOnly": true, "example": 12345 }, "view_url": { "description": "The URL where the attachment can be viewed, which may be friendlier to users in a browser than just directing them to a raw file. May be null if no view URL exists for the service.", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://www.dropbox.com/s/123/Screenshot.png" }, "connected_to_app": { "description": "Whether the attachment is connected to the app making the request for the purposes of showing an app components widget. Only present when the `resource_subtype` is `external` or `gdrive`.", "type": "boolean", "readOnly": true } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "attachments:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nAttachment result = client.attachments.createAttachmentForObject(file, parent, url, name)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\nconst fs = require(\"fs\");\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet attachmentsApiInstance = new Asana.AttachmentsApi();\nlet opts = { \n 'resource_subtype': \"external\", \n 'file': fs.createReadStream(\"file_example\"), \n 'parent': \"parent_example\", \n 'url': \"url_example\", \n 'name': \"name_example\", \n 'connect_to_app': true, \n 'opt_fields': \"connected_to_app,created_at,download_url,host,name,parent,parent.created_by,parent.name,parent.resource_subtype,permanent_url,resource_subtype,size,view_url\"\n};\nattachmentsApiInstance.createAttachmentForObject(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.attachments.createAttachmentForObject({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nattachments_api_instance = asana.AttachmentsApi(api_client)\nopts = {\n 'resource_subtype': \"external\", # str | \n 'file': \"file_example\", # str | \n 'parent': \"parent_example\", # str | \n 'url': \"url_example\", # str | \n 'name': \"name_example\", # str | \n 'connect_to_app': True, # bool | \n 'opt_fields': \"connected_to_app,created_at,download_url,host,name,parent,parent.created_by,parent.name,parent.resource_subtype,permanent_url,resource_subtype,size,view_url\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Upload an attachment\n api_response = attachments_api_instance.create_attachment_for_object(opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling AttachmentsApi->create_attachment_for_object: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.attachments.create_attachment_for_object({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "attachments->createAttachmentForObject(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.attachments.create_attachment_for_object(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 6, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/audit_log_events": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "start_at", "in": "query", "description": "Filter to events created after this time (inclusive).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_at", "in": "query", "description": "Filter to events created before this time (exclusive).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "event_type", "in": "query", "description": "Filter to events of this type.\nRefer to the [supported audit log events](/docs/audit-log-events#supported-audit-log-events) for a full list of values.", "required": false, "schema": { "type": "string" } }, { "name": "actor_type", "in": "query", "description": "Filter to events with an actor of this type.\nThis only needs to be included if querying for actor types without an ID. If `actor_gid` is included, this should be excluded.", "required": false, "schema": { "type": "string", "enum": [ "user", "asana", "asana_support", "anonymous", "external_administrator" ] } }, { "name": "actor_gid", "in": "query", "description": "Filter to events triggered by the actor with this ID.", "required": false, "schema": { "type": "string" } }, { "name": "resource_gid", "in": "query", "description": "Filter to events with this resource ID.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get audit log events", "description": "Retrieve the audit log events that have been captured in your domain.\n\nThis endpoint will return a list of [AuditLogEvent](/reference/audit-log-api) objects, sorted by creation time in ascending order. Note that the Audit Log API captures events from October 8th, 2021 and later. Queries for events before this date will not return results.\n\nThere are a number of query parameters (below) that can be used to filter the set of [AuditLogEvent](/reference/audit-log-api) objects that are returned in the response. Any combination of query parameters is valid. When no filters are provided, all of the events that have been captured in your domain will match.\n\nThe list of events will always be [paginated](/docs/pagination). The default limit is 1000 events. The next set of events can be retrieved using the `offset` from the previous response. If there are no events that match the provided filters in your domain, the endpoint will return `null` for the `next_page` field. Querying again with the same filters may return new events if they were captured after the last request. Once a response includes a `next_page` with an `offset`, subsequent requests can be made with the latest `offset` to poll for new events that match the provided filters.\n\n*Note: If the filters you provided match events in your domain and `next_page` is present in the response, we will continue to send `next_page` on subsequent requests even when there are no more events that match the filters. This was put in place so that you can implement an audit log stream that will return future events that match these filters. If you are not interested in future events that match the filters you have defined, you can rely on checking empty `data` response for the end of current events that match your filters.*\n\nWhen no `offset` is provided, the response will begin with the oldest events that match the provided filters. It is important to note that [AuditLogEvent](/reference/audit-log-api) objects will be permanently deleted from our systems after 90 days. If you wish to keep a permanent record of these events, we recommend using a SIEM tool to ingest and store these logs.", "tags": [ "Audit log API" ], "operationId": "getAuditLogEvents", "responses": { "200": { "description": "AuditLogEvents were successfully retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "An object representing a single event within an Asana domain.\n\nEvery audit log event is comprised of an `event_type`, `actor`, `resource`, and `context`. Some events will include additional metadata about the event under `details`. See our [currently supported list of events](/docs/audit-log-events#supported-audit-log-events) for more details.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the `AuditLogEvent`, as a string.", "type": "string", "example": "12345", "x-insert-after": false }, "created_at": { "description": "The time the event was created.", "type": "string", "format": "date-time", "example": "2021-01-01T00:00:00.000Z" }, "event_type": { "description": "The type of the event.", "type": "string", "example": "task_deleted" }, "event_category": { "description": "The category that this `event_type` belongs to.", "type": "string", "example": "deletion" }, "actor": { "description": "The entity that triggered the event. Will typically be a user.", "type": "object", "properties": { "actor_type": { "description": "The type of actor.\nCan be one of `user`, `asana`, `asana_support`, `anonymous`, or `external_administrator`.", "type": "string", "enum": [ "user", "asana", "asana_support", "anonymous", "external_administrator" ], "example": "user" }, "gid": { "description": "Globally unique identifier of the actor, if it is a user.", "type": "string", "example": "1111" }, "name": { "description": "The name of the actor, if it is a user.", "type": "string", "example": "Greg Sanchez" }, "email": { "description": "The email of the actor, if it is a user.", "type": "string", "example": "gregsanchez@example.com" } } }, "resource": { "description": "The primary object that was affected by this event.", "type": "object", "properties": { "resource_type": { "description": "The type of resource.", "type": "string", "example": "task" }, "resource_subtype": { "description": "The subtype of resource. Most resources will not have a subtype.", "type": "string", "example": "milestone" }, "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "name": { "description": "The name of the resource.", "type": "string", "nullable": true, "example": "Example Task" }, "email": { "description": "The email of the resource, if applicable.", "type": "string" } } }, "details": { "description": "Event specific details. The schema will vary depending on the `event_type`.", "type": "object", "properties": { "old_value": { "description": "The previous value of the field that was modified in the audited event.", "type": "string", "nullable": true }, "new_value": { "description": "The new value after the modification in the audited event.", "type": "string", "nullable": true }, "group": { "description": "The division or organizational unit where the event occurred. Primarily used to scope role change events (e.g., `user_division_admin_role_changed`), but may appear in other contexts involving group-level changes.", "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "context": { "description": "The context from which this event originated.", "type": "object", "properties": { "context_type": { "description": "The type of context.\nCan be one of `web`, `desktop`, `mobile`, `asana_support`, `asana`, `email`, or `api`.", "type": "string", "enum": [ "web", "desktop", "mobile", "asana_support", "asana", "email", "api" ], "example": "web" }, "api_authentication_method": { "description": "The authentication method used in the context of an API request.\nOnly present if the `context_type` is `api`. Can be one of `cookie`, `oauth`, `personal_access_token`, or `service_account`.", "type": "string", "enum": [ "cookie", "oauth", "personal_access_token", "service_account" ] }, "client_ip_address": { "description": "The IP address of the client that initiated the event, if applicable.", "type": "string", "example": "1.1.1.1" }, "user_agent": { "description": "The user agent of the client that initiated the event, if applicable.", "type": "string", "example": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36" }, "oauth_app_name": { "description": "The name of the OAuth App that initiated the event.\nOnly present if the `api_authentication_method` is `oauth`.", "type": "string" }, "rule_name": { "description": "The name of the automation rule that initiated the event.", "type": "string", "example": "When Task is added to this project" }, "on_behalf_of_user_id": { "description": "The ID of the user who requested a change via support.", "type": "integer", "example": 12345 } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.auditlogapi.getAuditLogEvents(workspaceGid, resourceGid, actorGid, actorType, eventType, endAt, startAt)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet auditLogApiApiInstance = new Asana.AuditLogAPIApi();\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'start_at': \"2013-10-20T19:20:30+01:00\", \n 'end_at': \"2013-10-20T19:20:30+01:00\", \n 'event_type': \"event_type_example\", \n 'actor_type': \"actor_type_example\", \n 'actor_gid': \"actor_gid_example\", \n 'resource_gid': \"resource_gid_example\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\"\n};\nauditLogApiApiInstance.getAuditLogEvents(workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.auditlogapi.getAuditLogEvents(workspaceGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\naudit_log_api_api_instance = asana.AuditLogAPIApi(api_client)\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'start_at': '2013-10-20T19:20:30+01:00', # datetime | Filter to events created after this time (inclusive).\n 'end_at': '2013-10-20T19:20:30+01:00', # datetime | Filter to events created before this time (exclusive).\n 'event_type': \"event_type_example\", # str | Filter to events of this type. Refer to the [supported audit log events](/docs/audit-log-events#supported-audit-log-events) for a full list of values.\n 'actor_type': \"actor_type_example\", # str | Filter to events with an actor of this type. This only needs to be included if querying for actor types without an ID. If `actor_gid` is included, this should be excluded.\n 'actor_gid': \"actor_gid_example\", # str | Filter to events triggered by the actor with this ID.\n 'resource_gid': \"resource_gid_example\", # str | Filter to events with this resource ID.\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n}\n\ntry:\n # Get audit log events\n api_response = audit_log_api_api_instance.get_audit_log_events(workspace_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling AuditLogAPIApi->get_audit_log_events: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.audit_log_api.get_audit_log_events(workspace_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "auditlogapi->getAuditLogEvents($workspace_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.audit_log_api.get_audit_log_events(workspace_gid: 'workspace_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/batch": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Submit parallel requests", "description": "Make multiple requests in parallel to Asana's API.", "tags": [ "Batch API" ], "operationId": "createBatchRequest", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "body", "headers", "status_code" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "body", "headers", "status_code" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The requests to batch together via the Batch API.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A request object for use in a batch request.", "type": "object", "properties": { "actions": { "type": "array", "items": { "description": "An action object for use in a batch request.", "type": "object", "properties": { "relative_path": { "description": "The path of the desired endpoint relative to the API\u2019s base URL. Query parameters are not accepted here; put them in `data` instead.", "type": "string", "example": "/tasks/123" }, "method": { "description": "The HTTP method you wish to emulate for the action.", "type": "string", "enum": [ "get", "post", "put", "delete", "patch", "head" ], "example": "get" }, "data": { "description": "For `GET` requests, this should be a map of query parameters you would have normally passed in the URL. Options and pagination are not accepted here; put them in `options` instead. For `POST`, `PATCH`, and `PUT` methods, this should be the content you would have normally put in the data field of the body.", "type": "object", "example": { "assignee": "me", "workspace": "1337" } }, "options": { "description": "Pagination (`limit` and `offset`) and output options (`fields` or `expand`) for the action. \u201cPretty\u201d JSON output is not an available option on individual actions; if you want pretty output, specify that option on the parent request.", "type": "object", "properties": { "limit": { "description": "Pagination limit for the request.", "type": "integer", "example": 50 }, "offset": { "description": "Pagination offset for the request.", "type": "integer", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "fields": { "description": "The fields to retrieve in the request.", "type": "array", "items": { "type": "string" }, "example": [ "name", "gid", "notes", "completed" ] } }, "example": { "limit": 3, "fields": [ "name", "notes", "completed" ] } } }, "required": [ "relative_path", "method" ] } } } } } } } } }, "responses": { "200": { "description": "Successfully completed the requested batch API operations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A response object returned from a batch request.", "type": "object", "properties": { "status_code": { "description": "The HTTP status code that the invoked endpoint returned.", "type": "integer", "example": 200 }, "headers": { "description": "A map of HTTP headers specific to this result. This is primarily used for returning a `Location` header to accompany a `201 Created` result. The parent HTTP response will contain all common headers.", "type": "object", "example": { "location": "/tasks/1234" } }, "body": { "description": "The JSON body that the invoked endpoint returned.", "type": "object", "example": { "data": { "gid": "1967", "completed": false, "name": "Hello, world!", "notes": "How are you today?" } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.batchapi.createBatchRequest()\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet batchApiApiInstance = new Asana.BatchAPIApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The requests to batch together via the Batch API.\nlet opts = { \n 'opt_fields': \"body,headers,status_code\"\n};\nbatchApiApiInstance.createBatchRequest(body, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.batchapi.createBatchRequest({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nbatch_api_api_instance = asana.BatchAPIApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The requests to batch together via the Batch API.\nopts = {\n 'opt_fields': \"body,headers,status_code\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Submit parallel requests\n api_response = batch_api_api_instance.create_batch_request(body, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling BatchAPIApi->create_batch_request: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.batch_api.create_batch_request({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "batchapi->createBatchRequest(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.batch_api.create_batch_request(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 5, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/custom_field_settings": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get a project's custom fields", "description": "Returns a list of all of the custom fields settings on a project, in compact form. Note that, as in all queries to collections which return compact representation, `opt_fields` can be used to include more data than is returned in the compact representation. See the [documentation for input/output options](https://developers.asana.com/docs/inputoutput-options) for more information.", "tags": [ "Custom field settings" ], "operationId": "getCustomFieldSettingsForProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "custom_field", "custom_field.asana_created_field", "custom_field.created_by", "custom_field.created_by.name", "custom_field.currency_code", "custom_field.custom_label", "custom_field.custom_label_position", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.default_access_level", "custom_field.description", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.format", "custom_field.has_notifications_enabled", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.is_global_to_workspace", "custom_field.is_value_read_only", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.people_value", "custom_field.people_value.name", "custom_field.precision", "custom_field.privacy_setting", "custom_field.reference_value", "custom_field.reference_value.name", "custom_field.representation_type", "custom_field.resource_subtype", "custom_field.text_value", "custom_field.type", "is_important", "offset", "parent", "parent.name", "path", "project", "project.name", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "custom_field", "custom_field.asana_created_field", "custom_field.created_by", "custom_field.created_by.name", "custom_field.currency_code", "custom_field.custom_label", "custom_field.custom_label_position", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.default_access_level", "custom_field.description", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.format", "custom_field.has_notifications_enabled", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.is_global_to_workspace", "custom_field.is_value_read_only", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.people_value", "custom_field.people_value.name", "custom_field.precision", "custom_field.privacy_setting", "custom_field.reference_value", "custom_field.reference_value.name", "custom_field.representation_type", "custom_field.resource_subtype", "custom_field.text_value", "custom_field.type", "is_important", "offset", "parent", "parent.name", "path", "project", "project.name", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved custom field settings objects for a project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.customfieldsettings.getCustomFieldSettingsForProject(projectGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet customFieldSettingsApiInstance = new Asana.CustomFieldSettingsApi();\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"custom_field,custom_field.asana_created_field,custom_field.created_by,custom_field.created_by.name,custom_field.currency_code,custom_field.custom_label,custom_field.custom_label_position,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.default_access_level,custom_field.description,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.format,custom_field.has_notifications_enabled,custom_field.id_prefix,custom_field.is_formula_field,custom_field.is_global_to_workspace,custom_field.is_value_read_only,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.people_value,custom_field.people_value.name,custom_field.precision,custom_field.privacy_setting,custom_field.representation_type,custom_field.resource_subtype,custom_field.text_value,custom_field.type,is_important,offset,parent,parent.name,path,project,project.name,uri\"\n};\ncustomFieldSettingsApiInstance.getCustomFieldSettingsForProject(project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.customfieldsettings.getCustomFieldSettingsForProject(projectGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ncustom_field_settings_api_instance = asana.CustomFieldSettingsApi(api_client)\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"custom_field,custom_field.asana_created_field,custom_field.created_by,custom_field.created_by.name,custom_field.currency_code,custom_field.custom_label,custom_field.custom_label_position,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.default_access_level,custom_field.description,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.format,custom_field.has_notifications_enabled,custom_field.id_prefix,custom_field.input_restrictions,custom_field.is_formula_field,custom_field.is_global_to_workspace,custom_field.is_value_read_only,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.people_value,custom_field.people_value.name,custom_field.precision,custom_field.privacy_setting,custom_field.reference_value,custom_field.reference_value.name,custom_field.representation_type,custom_field.resource_subtype,custom_field.text_value,custom_field.type,is_important,offset,parent,parent.name,path,project,project.name,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a project's custom fields\n api_response = custom_field_settings_api_instance.get_custom_field_settings_for_project(project_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling CustomFieldSettingsApi->get_custom_field_settings_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.custom_field_settings.get_custom_field_settings_for_project(project_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "customfieldsettings->getCustomFieldSettingsForProject($project_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.custom_field_settings.get_custom_field_settings_for_project(project_gid: 'project_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/portfolios/{portfolio_gid}/custom_field_settings": { "parameters": [ { "name": "portfolio_gid", "in": "path", "description": "Globally unique identifier for the portfolio.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get a portfolio's custom fields", "description": "Returns a list of all of the custom fields settings on a portfolio, in compact form.", "tags": [ "Custom field settings" ], "operationId": "getCustomFieldSettingsForPortfolio", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "custom_field", "custom_field.asana_created_field", "custom_field.created_by", "custom_field.created_by.name", "custom_field.currency_code", "custom_field.custom_label", "custom_field.custom_label_position", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.default_access_level", "custom_field.description", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.format", "custom_field.has_notifications_enabled", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.is_global_to_workspace", "custom_field.is_value_read_only", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.people_value", "custom_field.people_value.name", "custom_field.precision", "custom_field.privacy_setting", "custom_field.reference_value", "custom_field.reference_value.name", "custom_field.representation_type", "custom_field.resource_subtype", "custom_field.text_value", "custom_field.type", "is_important", "offset", "parent", "parent.name", "path", "project", "project.name", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "custom_field", "custom_field.asana_created_field", "custom_field.created_by", "custom_field.created_by.name", "custom_field.currency_code", "custom_field.custom_label", "custom_field.custom_label_position", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.default_access_level", "custom_field.description", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.format", "custom_field.has_notifications_enabled", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.is_global_to_workspace", "custom_field.is_value_read_only", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.people_value", "custom_field.people_value.name", "custom_field.precision", "custom_field.privacy_setting", "custom_field.reference_value", "custom_field.reference_value.name", "custom_field.representation_type", "custom_field.resource_subtype", "custom_field.text_value", "custom_field.type", "is_important", "offset", "parent", "parent.name", "path", "project", "project.name", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved custom field settings objects for a portfolio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.customfieldsettings.getCustomFieldSettingsForPortfolio(portfolioGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet customFieldSettingsApiInstance = new Asana.CustomFieldSettingsApi();\nlet portfolio_gid = \"12345\"; // String | Globally unique identifier for the portfolio.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"custom_field,custom_field.asana_created_field,custom_field.created_by,custom_field.created_by.name,custom_field.currency_code,custom_field.custom_label,custom_field.custom_label_position,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.default_access_level,custom_field.description,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.format,custom_field.has_notifications_enabled,custom_field.id_prefix,custom_field.is_formula_field,custom_field.is_global_to_workspace,custom_field.is_value_read_only,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.people_value,custom_field.people_value.name,custom_field.precision,custom_field.privacy_setting,custom_field.representation_type,custom_field.resource_subtype,custom_field.text_value,custom_field.type,is_important,offset,parent,parent.name,path,project,project.name,uri\"\n};\ncustomFieldSettingsApiInstance.getCustomFieldSettingsForPortfolio(portfolio_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.customfieldsettings.getCustomFieldSettingsForPortfolio(portfolioGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ncustom_field_settings_api_instance = asana.CustomFieldSettingsApi(api_client)\nportfolio_gid = \"12345\" # str | Globally unique identifier for the portfolio.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"custom_field,custom_field.asana_created_field,custom_field.created_by,custom_field.created_by.name,custom_field.currency_code,custom_field.custom_label,custom_field.custom_label_position,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.default_access_level,custom_field.description,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.format,custom_field.has_notifications_enabled,custom_field.id_prefix,custom_field.input_restrictions,custom_field.is_formula_field,custom_field.is_global_to_workspace,custom_field.is_value_read_only,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.people_value,custom_field.people_value.name,custom_field.precision,custom_field.privacy_setting,custom_field.reference_value,custom_field.reference_value.name,custom_field.representation_type,custom_field.resource_subtype,custom_field.text_value,custom_field.type,is_important,offset,parent,parent.name,path,project,project.name,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a portfolio's custom fields\n api_response = custom_field_settings_api_instance.get_custom_field_settings_for_portfolio(portfolio_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling CustomFieldSettingsApi->get_custom_field_settings_for_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.custom_field_settings.get_custom_field_settings_for_portfolio(portfolio_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "customfieldsettings->getCustomFieldSettingsForPortfolio($portfolio_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.custom_field_settings.get_custom_field_settings_for_portfolio(portfolio_gid: 'portfolio_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/custom_fields": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Create a custom field", "description": "Required scope: custom_fields:write\n\nCreates a new custom field in a workspace. Every custom field is required\nto be created in a specific workspace, and this workspace cannot be\nchanged once set.\n\nA custom field\u2019s name must be unique within a workspace and not conflict\nwith names of existing task properties such as `Due Date` or `Assignee`.\nA custom field\u2019s type must be one of `text`, `enum`, `multi_enum`, `number`,\n`date`, or `people`.\n\nReturns the full record of the newly created custom field.", "tags": [ "Custom fields" ], "operationId": "createCustomField", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "asana_created_field", "created_by", "created_by.name", "currency_code", "custom_label", "custom_label_position", "date_value", "date_value.date", "date_value.date_time", "default_access_level", "description", "display_value", "enabled", "enum_options", "enum_options.color", "enum_options.enabled", "enum_options.name", "enum_value", "enum_value.color", "enum_value.enabled", "enum_value.name", "format", "has_notifications_enabled", "id_prefix", "input_restrictions", "is_formula_field", "is_global_to_workspace", "is_value_read_only", "multi_enum_values", "multi_enum_values.color", "multi_enum_values.enabled", "multi_enum_values.name", "name", "number_value", "people_value", "people_value.name", "precision", "privacy_setting", "reference_value", "reference_value.name", "representation_type", "resource_subtype", "text_value", "type" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "asana_created_field", "created_by", "created_by.name", "currency_code", "custom_label", "custom_label_position", "date_value", "date_value.date", "date_value.date_time", "default_access_level", "description", "display_value", "enabled", "enum_options", "enum_options.color", "enum_options.enabled", "enum_options.name", "enum_value", "enum_value.color", "enum_value.enabled", "enum_value.name", "format", "has_notifications_enabled", "id_prefix", "input_restrictions", "is_formula_field", "is_global_to_workspace", "is_value_read_only", "multi_enum_values", "multi_enum_values.color", "multi_enum_values.enabled", "multi_enum_values.name", "name", "number_value", "people_value", "people_value.name", "precision", "privacy_setting", "reference_value", "reference_value.name", "representation_type", "resource_subtype", "text_value", "type" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The custom field object to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "required": [ "workspace" ], "properties": { "workspace": { "type": "string", "description": "*Create-Only* The workspace to create a custom field in.", "example": "1331" }, "owned_by_app": { "type": "boolean", "description": "*Allow-listed*. Instructs the API that this Custom Field is app-owned. This parameter is allow-listed to specific apps at this point in time. For apps that are not allow-listed, providing this parameter will result in a `403 Forbidden`." }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of user GIDs reflects the users to be written to a `people` custom field. Note that *write* operations will replace existing users (if any) in the custom field with the users specified in this array.", "type": "array", "items": { "type": "string", "description": "The GID of a user." }, "example": [ "12345" ] }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of GIDs reflects the objects to be written to a `reference` custom field. Note that *write* operations will replace existing objects (if any) in the custom field with the objects specified in this array.", "type": "array", "items": { "type": "string", "description": "The GID of an object." }, "example": [ "12345" ] } } } ] }, { "type": "object", "required": [ "resource_subtype" ], "properties": { "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.", "type": "string", "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] } } } } } }, "responses": { "201": { "description": "Custom field successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "custom_fields:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nCustomField result = client.customfields.createCustomField()\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet customFieldsApiInstance = new Asana.CustomFieldsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The custom field object to create.\nlet opts = { \n 'opt_fields': \"asana_created_field,created_by,created_by.name,currency_code,custom_label,custom_label_position,date_value,date_value.date,date_value.date_time,default_access_level,description,display_value,enabled,enum_options,enum_options.color,enum_options.enabled,enum_options.name,enum_value,enum_value.color,enum_value.enabled,enum_value.name,format,has_notifications_enabled,id_prefix,is_formula_field,is_global_to_workspace,is_value_read_only,multi_enum_values,multi_enum_values.color,multi_enum_values.enabled,multi_enum_values.name,name,number_value,people_value,people_value.name,precision,privacy_setting,representation_type,resource_subtype,text_value,type\"\n};\ncustomFieldsApiInstance.createCustomField(body, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.customfields.createCustomField({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ncustom_fields_api_instance = asana.CustomFieldsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The custom field object to create.\nopts = {\n 'opt_fields': \"asana_created_field,created_by,created_by.name,currency_code,custom_label,custom_label_position,date_value,date_value.date,date_value.date_time,default_access_level,description,display_value,enabled,enum_options,enum_options.color,enum_options.enabled,enum_options.name,enum_value,enum_value.color,enum_value.enabled,enum_value.name,format,has_notifications_enabled,id_prefix,input_restrictions,is_formula_field,is_global_to_workspace,is_value_read_only,multi_enum_values,multi_enum_values.color,multi_enum_values.enabled,multi_enum_values.name,name,number_value,people_value,people_value.name,precision,privacy_setting,reference_value,reference_value.name,representation_type,resource_subtype,text_value,type\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a custom field\n api_response = custom_fields_api_instance.create_custom_field(body, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling CustomFieldsApi->create_custom_field: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.custom_fields.create_custom_field({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "customfields->createCustomField(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.custom_fields.create_custom_field(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 48, "x-moar-complexity-skipped": false } }, "/custom_fields/{custom_field_gid}": { "parameters": [ { "name": "custom_field_gid", "in": "path", "description": "Globally unique identifier for the custom field.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "custom_field" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a custom field", "description": "Required scope: custom_fields:read\n\nGet the complete definition of a custom field\u2019s metadata.\n\nSince custom fields can be defined for one of a number of types, and\nthese types have different data and behaviors, there are fields that are\nrelevant to a particular type. For instance, as noted above, enum_options\nis only relevant for the enum type and defines the set of choices that\nthe enum could represent. The examples below show some of these\ntype-specific custom field definitions.", "tags": [ "Custom fields" ], "operationId": "getCustomField", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "asana_created_field", "created_by", "created_by.name", "currency_code", "custom_label", "custom_label_position", "date_value", "date_value.date", "date_value.date_time", "default_access_level", "description", "display_value", "enabled", "enum_options", "enum_options.color", "enum_options.enabled", "enum_options.name", "enum_value", "enum_value.color", "enum_value.enabled", "enum_value.name", "format", "has_notifications_enabled", "id_prefix", "input_restrictions", "is_formula_field", "is_global_to_workspace", "is_value_read_only", "multi_enum_values", "multi_enum_values.color", "multi_enum_values.enabled", "multi_enum_values.name", "name", "number_value", "people_value", "people_value.name", "precision", "privacy_setting", "reference_value", "reference_value.name", "representation_type", "resource_subtype", "text_value", "type" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "asana_created_field", "created_by", "created_by.name", "currency_code", "custom_label", "custom_label_position", "date_value", "date_value.date", "date_value.date_time", "default_access_level", "description", "display_value", "enabled", "enum_options", "enum_options.color", "enum_options.enabled", "enum_options.name", "enum_value", "enum_value.color", "enum_value.enabled", "enum_value.name", "format", "has_notifications_enabled", "id_prefix", "input_restrictions", "is_formula_field", "is_global_to_workspace", "is_value_read_only", "multi_enum_values", "multi_enum_values.color", "multi_enum_values.enabled", "multi_enum_values.name", "name", "number_value", "people_value", "people_value.name", "precision", "privacy_setting", "reference_value", "reference_value.name", "representation_type", "resource_subtype", "text_value", "type" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the complete definition of a custom field\u2019s metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "custom_fields:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nCustomField result = client.customfields.getCustomField(customFieldGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet customFieldsApiInstance = new Asana.CustomFieldsApi();\nlet custom_field_gid = \"12345\"; // String | Globally unique identifier for the custom field.\nlet opts = { \n 'opt_fields': \"asana_created_field,created_by,created_by.name,currency_code,custom_label,custom_label_position,date_value,date_value.date,date_value.date_time,default_access_level,description,display_value,enabled,enum_options,enum_options.color,enum_options.enabled,enum_options.name,enum_value,enum_value.color,enum_value.enabled,enum_value.name,format,has_notifications_enabled,id_prefix,is_formula_field,is_global_to_workspace,is_value_read_only,multi_enum_values,multi_enum_values.color,multi_enum_values.enabled,multi_enum_values.name,name,number_value,people_value,people_value.name,precision,privacy_setting,representation_type,resource_subtype,text_value,type\"\n};\ncustomFieldsApiInstance.getCustomField(custom_field_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.customfields.getCustomField(customFieldGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ncustom_fields_api_instance = asana.CustomFieldsApi(api_client)\ncustom_field_gid = \"12345\" # str | Globally unique identifier for the custom field.\nopts = {\n 'opt_fields': \"asana_created_field,created_by,created_by.name,currency_code,custom_label,custom_label_position,date_value,date_value.date,date_value.date_time,default_access_level,description,display_value,enabled,enum_options,enum_options.color,enum_options.enabled,enum_options.name,enum_value,enum_value.color,enum_value.enabled,enum_value.name,format,has_notifications_enabled,id_prefix,input_restrictions,is_formula_field,is_global_to_workspace,is_value_read_only,multi_enum_values,multi_enum_values.color,multi_enum_values.enabled,multi_enum_values.name,name,number_value,people_value,people_value.name,precision,privacy_setting,reference_value,reference_value.name,representation_type,resource_subtype,text_value,type\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a custom field\n api_response = custom_fields_api_instance.get_custom_field(custom_field_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling CustomFieldsApi->get_custom_field: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.custom_fields.get_custom_field(custom_field_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "customfields->getCustomField($custom_field_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.custom_fields.get_custom_field(custom_field_gid: 'custom_field_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a custom field", "description": "Required scope: custom_fields:write\n\nA specific, existing custom field can be updated by making a PUT request on the URL for that custom field. Only the fields provided in the `data` block will be updated; any unspecified fields will remain unchanged\nWhen using this method, it is best to specify only those fields you wish to change, or else you may overwrite changes made by another user since you last retrieved the custom field.\nA custom field\u2019s `type` cannot be updated.\nAn enum custom field\u2019s `enum_options` cannot be updated with this endpoint. Instead see \u201cWork With Enum Options\u201d for information on how to update `enum_options`.\nLocked custom fields can only be updated by the user who locked the field.\nReturns the complete updated custom field record.", "tags": [ "Custom fields" ], "operationId": "updateCustomField", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "asana_created_field", "created_by", "created_by.name", "currency_code", "custom_label", "custom_label_position", "date_value", "date_value.date", "date_value.date_time", "default_access_level", "description", "display_value", "enabled", "enum_options", "enum_options.color", "enum_options.enabled", "enum_options.name", "enum_value", "enum_value.color", "enum_value.enabled", "enum_value.name", "format", "has_notifications_enabled", "id_prefix", "input_restrictions", "is_formula_field", "is_global_to_workspace", "is_value_read_only", "multi_enum_values", "multi_enum_values.color", "multi_enum_values.enabled", "multi_enum_values.name", "name", "number_value", "people_value", "people_value.name", "precision", "privacy_setting", "reference_value", "reference_value.name", "representation_type", "resource_subtype", "text_value", "type" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "asana_created_field", "created_by", "created_by.name", "currency_code", "custom_label", "custom_label_position", "date_value", "date_value.date", "date_value.date_time", "default_access_level", "description", "display_value", "enabled", "enum_options", "enum_options.color", "enum_options.enabled", "enum_options.name", "enum_value", "enum_value.color", "enum_value.enabled", "enum_value.name", "format", "has_notifications_enabled", "id_prefix", "input_restrictions", "is_formula_field", "is_global_to_workspace", "is_value_read_only", "multi_enum_values", "multi_enum_values.color", "multi_enum_values.enabled", "multi_enum_values.name", "name", "number_value", "people_value", "people_value.name", "precision", "privacy_setting", "reference_value", "reference_value.name", "representation_type", "resource_subtype", "text_value", "type" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The custom field object with all updated properties.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "required": [ "workspace" ], "properties": { "workspace": { "type": "string", "description": "*Create-Only* The workspace to create a custom field in.", "example": "1331" }, "owned_by_app": { "type": "boolean", "description": "*Allow-listed*. Instructs the API that this Custom Field is app-owned. This parameter is allow-listed to specific apps at this point in time. For apps that are not allow-listed, providing this parameter will result in a `403 Forbidden`." }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of user GIDs reflects the users to be written to a `people` custom field. Note that *write* operations will replace existing users (if any) in the custom field with the users specified in this array.", "type": "array", "items": { "type": "string", "description": "The GID of a user." }, "example": [ "12345" ] }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of GIDs reflects the objects to be written to a `reference` custom field. Note that *write* operations will replace existing objects (if any) in the custom field with the objects specified in this array.", "type": "array", "items": { "type": "string", "description": "The GID of an object." }, "example": [ "12345" ] } } } ] } } } } } }, "responses": { "200": { "description": "The custom field was successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "custom_fields:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nCustomField result = client.customfields.updateCustomField(customFieldGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet customFieldsApiInstance = new Asana.CustomFieldsApi();\nlet custom_field_gid = \"12345\"; // String | Globally unique identifier for the custom field.\nlet opts = { \n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, \n 'opt_fields': \"asana_created_field,created_by,created_by.name,currency_code,custom_label,custom_label_position,date_value,date_value.date,date_value.date_time,default_access_level,description,display_value,enabled,enum_options,enum_options.color,enum_options.enabled,enum_options.name,enum_value,enum_value.color,enum_value.enabled,enum_value.name,format,has_notifications_enabled,id_prefix,is_formula_field,is_global_to_workspace,is_value_read_only,multi_enum_values,multi_enum_values.color,multi_enum_values.enabled,multi_enum_values.name,name,number_value,people_value,people_value.name,precision,privacy_setting,representation_type,resource_subtype,text_value,type\"\n};\ncustomFieldsApiInstance.updateCustomField(custom_field_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.customfields.updateCustomField(customFieldGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ncustom_fields_api_instance = asana.CustomFieldsApi(api_client)\ncustom_field_gid = \"12345\" # str | Globally unique identifier for the custom field.\nopts = {\n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, # dict | The custom field object with all updated properties.\n 'opt_fields': \"asana_created_field,created_by,created_by.name,currency_code,custom_label,custom_label_position,date_value,date_value.date,date_value.date_time,default_access_level,description,display_value,enabled,enum_options,enum_options.color,enum_options.enabled,enum_options.name,enum_value,enum_value.color,enum_value.enabled,enum_value.name,format,has_notifications_enabled,id_prefix,input_restrictions,is_formula_field,is_global_to_workspace,is_value_read_only,multi_enum_values,multi_enum_values.color,multi_enum_values.enabled,multi_enum_values.name,name,number_value,people_value,people_value.name,precision,privacy_setting,reference_value,reference_value.name,representation_type,resource_subtype,text_value,type\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a custom field\n api_response = custom_fields_api_instance.update_custom_field(custom_field_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling CustomFieldsApi->update_custom_field: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.custom_fields.update_custom_field(custom_field_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "customfields->updateCustomField($custom_field_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.custom_fields.update_custom_field(custom_field_gid: 'custom_field_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 47, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a custom field", "description": "A specific, existing custom field can be deleted by making a DELETE request on the URL for that custom field.\nLocked custom fields can only be deleted by the user who locked the field.\nReturns an empty data record.", "tags": [ "Custom fields" ], "operationId": "deleteCustomField", "responses": { "200": { "description": "The custom field was successfully deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.customfields.deleteCustomField(customFieldGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet customFieldsApiInstance = new Asana.CustomFieldsApi();\nlet custom_field_gid = \"12345\"; // String | Globally unique identifier for the custom field.\n\ncustomFieldsApiInstance.deleteCustomField(custom_field_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.customfields.deleteCustomField(customFieldGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ncustom_fields_api_instance = asana.CustomFieldsApi(api_client)\ncustom_field_gid = \"12345\" # str | Globally unique identifier for the custom field.\n\n\ntry:\n # Delete a custom field\n api_response = custom_fields_api_instance.delete_custom_field(custom_field_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling CustomFieldsApi->delete_custom_field: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.custom_fields.delete_custom_field(custom_field_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "customfields->deleteCustomField($custom_field_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.custom_fields.delete_custom_field(custom_field_gid: 'custom_field_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/custom_fields": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get a workspace's custom fields", "description": "Required scope: custom_fields:read\n\nReturns a list of the compact representation of all of the custom fields in a workspace.", "tags": [ "Custom fields" ], "operationId": "getCustomFieldsForWorkspace", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "asana_created_field", "created_by", "created_by.name", "currency_code", "custom_label", "custom_label_position", "date_value", "date_value.date", "date_value.date_time", "default_access_level", "description", "display_value", "enabled", "enum_options", "enum_options.color", "enum_options.enabled", "enum_options.name", "enum_value", "enum_value.color", "enum_value.enabled", "enum_value.name", "format", "has_notifications_enabled", "id_prefix", "input_restrictions", "is_formula_field", "is_global_to_workspace", "is_value_read_only", "multi_enum_values", "multi_enum_values.color", "multi_enum_values.enabled", "multi_enum_values.name", "name", "number_value", "offset", "path", "people_value", "people_value.name", "precision", "privacy_setting", "reference_value", "reference_value.name", "representation_type", "resource_subtype", "text_value", "type", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "asana_created_field", "created_by", "created_by.name", "currency_code", "custom_label", "custom_label_position", "date_value", "date_value.date", "date_value.date_time", "default_access_level", "description", "display_value", "enabled", "enum_options", "enum_options.color", "enum_options.enabled", "enum_options.name", "enum_value", "enum_value.color", "enum_value.enabled", "enum_value.name", "format", "has_notifications_enabled", "id_prefix", "input_restrictions", "is_formula_field", "is_global_to_workspace", "is_value_read_only", "multi_enum_values", "multi_enum_values.color", "multi_enum_values.enabled", "multi_enum_values.name", "name", "number_value", "offset", "path", "people_value", "people_value.name", "precision", "privacy_setting", "reference_value", "reference_value.name", "representation_type", "resource_subtype", "text_value", "type", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved all custom fields for the given workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "custom_fields:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.customfields.getCustomFieldsForWorkspace(workspaceGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet customFieldsApiInstance = new Asana.CustomFieldsApi();\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"asana_created_field,created_by,created_by.name,currency_code,custom_label,custom_label_position,date_value,date_value.date,date_value.date_time,default_access_level,description,display_value,enabled,enum_options,enum_options.color,enum_options.enabled,enum_options.name,enum_value,enum_value.color,enum_value.enabled,enum_value.name,format,has_notifications_enabled,id_prefix,is_formula_field,is_global_to_workspace,is_value_read_only,multi_enum_values,multi_enum_values.color,multi_enum_values.enabled,multi_enum_values.name,name,number_value,offset,path,people_value,people_value.name,precision,privacy_setting,representation_type,resource_subtype,text_value,type,uri\"\n};\ncustomFieldsApiInstance.getCustomFieldsForWorkspace(workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.customfields.getCustomFieldsForWorkspace(workspaceGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ncustom_fields_api_instance = asana.CustomFieldsApi(api_client)\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"asana_created_field,created_by,created_by.name,currency_code,custom_label,custom_label_position,date_value,date_value.date,date_value.date_time,default_access_level,description,display_value,enabled,enum_options,enum_options.color,enum_options.enabled,enum_options.name,enum_value,enum_value.color,enum_value.enabled,enum_value.name,format,has_notifications_enabled,id_prefix,input_restrictions,is_formula_field,is_global_to_workspace,is_value_read_only,multi_enum_values,multi_enum_values.color,multi_enum_values.enabled,multi_enum_values.name,name,number_value,offset,path,people_value,people_value.name,precision,privacy_setting,reference_value,reference_value.name,representation_type,resource_subtype,text_value,type,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a workspace's custom fields\n api_response = custom_fields_api_instance.get_custom_fields_for_workspace(workspace_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling CustomFieldsApi->get_custom_fields_for_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.custom_fields.get_custom_fields_for_workspace(workspace_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "customfields->getCustomFieldsForWorkspace($workspace_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.custom_fields.get_custom_fields_for_workspace(workspace_gid: 'workspace_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/custom_fields/{custom_field_gid}/enum_options": { "parameters": [ { "name": "custom_field_gid", "in": "path", "description": "Globally unique identifier for the custom field.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "custom_field" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Create an enum option", "description": "Required scope: custom_fields:write\n\nCreates an enum option and adds it to this custom field\u2019s list of enum options. A custom field can have at most 500 enum options (including disabled options). By default new enum options are inserted at the end of a custom field\u2019s list.\nLocked custom fields can only have enum options added by the user who locked the field.\nReturns the full record of the newly created enum option.", "tags": [ "Custom fields" ], "operationId": "createEnumOptionForCustomField", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "enabled", "name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "enabled", "name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The enum option object to create.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "properties": { "insert_before": { "type": "string", "description": "An existing enum option within this custom field before which the new enum option should be inserted. Cannot be provided together with after_enum_option.", "example": "12345" }, "insert_after": { "type": "string", "description": "An existing enum option within this custom field after which the new enum option should be inserted. Cannot be provided together with before_enum_option.", "example": "12345" } } } ] } } } } } }, "responses": { "201": { "description": "Custom field enum option successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "custom_fields:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.customfields.createEnumOptionForCustomField(customFieldGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet customFieldsApiInstance = new Asana.CustomFieldsApi();\nlet custom_field_gid = \"12345\"; // String | Globally unique identifier for the custom field.\nlet opts = { \n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, \n 'opt_fields': \"color,enabled,name\"\n};\ncustomFieldsApiInstance.createEnumOptionForCustomField(custom_field_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.customfields.createEnumOptionForCustomField(customFieldGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ncustom_fields_api_instance = asana.CustomFieldsApi(api_client)\ncustom_field_gid = \"12345\" # str | Globally unique identifier for the custom field.\nopts = {\n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, # dict | The enum option object to create.\n 'opt_fields': \"color,enabled,name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create an enum option\n api_response = custom_fields_api_instance.create_enum_option_for_custom_field(custom_field_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling CustomFieldsApi->create_enum_option_for_custom_field: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.custom_fields.create_enum_option_for_custom_field(custom_field_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "customfields->createEnumOptionForCustomField($custom_field_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.custom_fields.create_enum_option_for_custom_field(custom_field_gid: 'custom_field_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 7, "x-moar-complexity-skipped": false } }, "/custom_fields/{custom_field_gid}/enum_options/insert": { "parameters": [ { "name": "custom_field_gid", "in": "path", "description": "Globally unique identifier for the custom field.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "custom_field" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Reorder a custom field's enum", "description": "Required scope: custom_fields:write\n\nMoves a particular enum option to be either before or after another specified enum option in the custom field.\nLocked custom fields can only be reordered by the user who locked the field.", "tags": [ "Custom fields" ], "operationId": "insertEnumOptionForCustomField", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "enabled", "name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "enabled", "name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The enum option object to create.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "enum_option" ], "properties": { "enum_option": { "type": "string", "description": "The gid of the enum option to relocate.", "example": "97285" }, "before_enum_option": { "type": "string", "description": "An existing enum option within this custom field before which the new enum option should be inserted. Cannot be provided together with after_enum_option.", "example": "12345" }, "after_enum_option": { "type": "string", "description": "An existing enum option within this custom field after which the new enum option should be inserted. Cannot be provided together with before_enum_option.", "example": "12345" } } } } } } } }, "responses": { "200": { "description": "Custom field enum option successfully reordered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "custom_fields:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.customfields.insertEnumOptionForCustomField(customFieldGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet customFieldsApiInstance = new Asana.CustomFieldsApi();\nlet custom_field_gid = \"12345\"; // String | Globally unique identifier for the custom field.\nlet opts = { \n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, \n 'opt_fields': \"color,enabled,name\"\n};\ncustomFieldsApiInstance.insertEnumOptionForCustomField(custom_field_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.customfields.insertEnumOptionForCustomField(customFieldGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ncustom_fields_api_instance = asana.CustomFieldsApi(api_client)\ncustom_field_gid = \"12345\" # str | Globally unique identifier for the custom field.\nopts = {\n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, # dict | The enum option object to create.\n 'opt_fields': \"color,enabled,name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Reorder a custom field's enum\n api_response = custom_fields_api_instance.insert_enum_option_for_custom_field(custom_field_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling CustomFieldsApi->insert_enum_option_for_custom_field: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.custom_fields.insert_enum_option_for_custom_field(custom_field_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "customfields->insertEnumOptionForCustomField($custom_field_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.custom_fields.insert_enum_option_for_custom_field(custom_field_gid: 'custom_field_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 3, "x-moar-complexity-skipped": false } }, "/enum_options/{enum_option_gid}": { "parameters": [ { "name": "enum_option_gid", "in": "path", "required": true, "description": "Globally unique identifier for the enum option.", "schema": { "type": "string" }, "example": "124578" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "put": { "summary": "Update an enum option", "description": "Required scope: custom_fields:write\n\nUpdates an existing enum option. Enum custom fields require at least one enabled enum option.\nLocked custom fields can only be updated by the user who locked the field.\nReturns the full record of the updated enum option.", "tags": [ "Custom fields" ], "operationId": "updateEnumOption", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "enabled", "name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "enabled", "name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The enum option object to update", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } } } } } }, "responses": { "200": { "description": "Successfully updated the specified custom field enum.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "custom_fields:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.customfields.updateEnumOption(enumOptionGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet customFieldsApiInstance = new Asana.CustomFieldsApi();\nlet enum_option_gid = \"124578\"; // String | Globally unique identifier for the enum option.\nlet opts = { \n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, \n 'opt_fields': \"color,enabled,name\"\n};\ncustomFieldsApiInstance.updateEnumOption(enum_option_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.customfields.updateEnumOption(enumOptionGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ncustom_fields_api_instance = asana.CustomFieldsApi(api_client)\nenum_option_gid = \"124578\" # str | Globally unique identifier for the enum option.\nopts = {\n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, # dict | The enum option object to update\n 'opt_fields': \"color,enabled,name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update an enum option\n api_response = custom_fields_api_instance.update_enum_option(enum_option_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling CustomFieldsApi->update_enum_option: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.custom_fields.update_enum_option(enum_option_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "customfields->updateEnumOption($enum_option_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.custom_fields.update_enum_option(enum_option_gid: 'enum_option_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 5, "x-moar-complexity-skipped": false } }, "/custom_types": { "parameters": [ { "name": "project", "in": "query", "description": "Globally unique identifier for the project, which is used as a filter when retrieving all custom types.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get all custom types associated with an object", "description": "Returns a list of all of the custom types associated with an object. Currently, only projects are supported. Note that, as in all queries to collections which return compact representation, `opt_fields` can be used to include more data than is returned in the compact representation. See the [documentation for input/output options](https://developers.asana.com/docs/inputoutput-options) for more information.", "tags": [ "Custom types" ], "operationId": "getCustomTypes", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "name", "offset", "path", "status_options", "status_options.color", "status_options.completion_state", "status_options.enabled", "status_options.name", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "offset", "path", "status_options", "status_options.color", "status_options.completion_state", "status_options.enabled", "status_options.name", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved custom types", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "description": "Custom Types extend the types of Asana Objects, currently only Custom Tasks are supported.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type.", "example": "Bug ticket" } } }, { "type": "object", "properties": { "status_options": { "type": "array", "nullable": true, "description": "The available options for the custom type.", "items": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type_status_option", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type status option.", "example": "Solution pending" } } }, { "type": "object", "properties": { "completion_state": { "description": "The completion state the custom type status option corresponds to, all custom types must have one \u2018Incomplete\u2019 and \u2018Complete\u2019 status option.", "type": "string", "example": "Incomplete", "nullable": true }, "enabled": { "description": "Whether or not the custom type status option is a selectable value for the custom type.", "type": "boolean", "example": true, "nullable": true }, "color": { "description": "The color associated with the custom type status option. Defaults to \u2018none\u2019.", "type": "string", "example": "blue", "nullable": true } } } ] } } } } ] } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet customTypesApiInstance = new Asana.CustomTypesApi();\nlet project = \"1331\"; // String | Globally unique identifier for the project, which is used as a filter when retrieving all custom types.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"name,offset,path,status_options,status_options.color,status_options.completion_state,status_options.enabled,status_options.name,uri\"\n};\ncustomTypesApiInstance.getCustomTypes(project, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ncustom_types_api_instance = asana.CustomTypesApi(api_client)\nproject = \"1331\" # str | Globally unique identifier for the project, which is used as a filter when retrieving all custom types.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"name,offset,path,status_options,status_options.color,status_options.completion_state,status_options.enabled,status_options.name,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get all custom types associated with an object\n api_response = custom_types_api_instance.get_custom_types(project, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling CustomTypesApi->get_custom_types: %s\\n\" % e)", "name": "python-sdk-v5" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/custom_types/{custom_type_gid}": { "parameters": [ { "name": "custom_type_gid", "in": "path", "description": "Globally unique identifier for the custom type.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a custom type", "description": "Returns the complete custom type record for a single custom type.", "tags": [ "Custom types" ], "operationId": "getCustomType", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "name", "status_options", "status_options.color", "status_options.completion_state", "status_options.enabled", "status_options.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "status_options", "status_options.color", "status_options.completion_state", "status_options.enabled", "status_options.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested custom type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "Custom Types extend the types of Asana Objects, currently only Custom Tasks are supported.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type.", "example": "Bug ticket" } } }, { "type": "object", "properties": { "status_options": { "type": "array", "nullable": true, "description": "The available options for the custom type.", "items": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type_status_option", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type status option.", "example": "Solution pending" } } }, { "type": "object", "properties": { "completion_state": { "description": "The completion state the custom type status option corresponds to, all custom types must have one \u2018Incomplete\u2019 and \u2018Complete\u2019 status option.", "type": "string", "example": "Incomplete", "nullable": true }, "enabled": { "description": "Whether or not the custom type status option is a selectable value for the custom type.", "type": "boolean", "example": true, "nullable": true }, "color": { "description": "The color associated with the custom type status option. Defaults to \u2018none\u2019.", "type": "string", "example": "blue", "nullable": true } } } ] } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet customTypesApiInstance = new Asana.CustomTypesApi();\nlet custom_type_gid = \"12345\"; // String | Globally unique identifier for the custom type.\nlet opts = { \n 'opt_fields': \"name,status_options,status_options.color,status_options.completion_state,status_options.enabled,status_options.name\"\n};\ncustomTypesApiInstance.getCustomType(custom_type_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ncustom_types_api_instance = asana.CustomTypesApi(api_client)\ncustom_type_gid = \"12345\" # str | Globally unique identifier for the custom type.\nopts = {\n 'opt_fields': \"name,status_options,status_options.color,status_options.completion_state,status_options.enabled,status_options.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a custom type\n api_response = custom_types_api_instance.get_custom_type(custom_type_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling CustomTypesApi->get_custom_type: %s\\n\" % e)", "name": "python-sdk-v5" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/events": { "parameters": [ { "name": "resource", "in": "query", "required": true, "description": "A resource ID to subscribe to. The resource can be a task, project, or goal.", "schema": { "type": "string" }, "example": "12345" }, { "name": "sync", "in": "query", "required": false, "description": "A sync token received from the last request, or none on first sync. Events will be returned from the point in time that the sync token was generated.\n*Note: On your first request, omit the sync token. The response will be the same as for an expired sync token, and will include a new valid sync token.If the sync token is too old (which may happen from time to time) the API will return a `412 Precondition Failed` error, and include a fresh sync token in the response.*", "schema": { "type": "string" }, "example": "de4774f6915eae04714ca93bb2f5ee81" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get events on a resource", "description": "Returns the full record for all events that have occurred since the sync\ntoken was created.\n\nA `GET` request to the endpoint `/[path_to_resource]/events` can be made in\nlieu of including the resource ID in the data for the request.\n\nAsana limits a single sync token to 100 events. If more than 100 events exist\nfor a given resource, `has_more: true` will be returned in the response, indicating\nthat there are more events to pull.\n\n*Note: The resource returned will be the resource that triggered the\nevent. This may be different from the one that the events were requested\nfor. For example, a subscription to a project will contain events for\ntasks contained within the project.*", "tags": [ "Events" ], "operationId": "getEvents", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "action", "change", "change.action", "change.added_value", "change.field", "change.new_value", "change.removed_value", "created_at", "parent", "parent.name", "resource", "resource.name", "type", "user", "user.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "action", "change", "change.action", "change.added_value", "change.field", "change.new_value", "change.removed_value", "created_at", "parent", "parent.name", "resource", "resource.name", "type", "user", "user.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved events.", "content": { "application/json": { "schema": { "type": "object", "description": "The full record for all events that have occurred since the sync token was created.", "properties": { "data": { "type": "array", "items": { "description": "An *event* is an object representing a change to a resource that was\nobserved by an event subscription or delivered asynchronously to\nthe target location of an active webhook.\n\nThe event may be triggered by a different `user` than the\nsubscriber. For example, if user A subscribes to a task and user B\nmodified it, the event's user will be user B. Note: Some events\nare generated by the system, and will have `null` as the user. API\nconsumers should make sure to handle this case.\n\nThe `resource` that triggered the event may be different from the one\nthat the events were requested for or the webhook is subscribed to. For\nexample, a subscription to a project will contain events for tasks\ncontained within the project.\n\n**Note:** pay close attention to the relationship between the fields\n`Event.action` and `Event.change.action`.\n`Event.action` represents the action taken on the resource\nitself, and `Event.change.action` represents how the information\nwithin the resource's fields have been modified.\n\nFor instance, consider these scenarios:\n\n\n* When at task is added to a project, `Event.action` will be\n`added`, `Event.parent` will be an object with the `id` and\n`type` of the project, and there will be no `change` field.\n\n\n* When an assignee is set on the task, `Event.parent` will be\n`null`, `Event.action` will be `changed`,\n`Event.change.action` will be `changed`, and `new_value` will\nbe an object with the user's `id` and `type`.\n\n\n* When a collaborator is added to the task, `Event.parent` will\nbe `null`, `Event.action` will be `changed`,\n`Event.change.action` will be `added`, and `added_value` will be\nan object with the user's `id` and `type`.", "type": "object", "properties": { "user": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "description": "The user who triggered the event." } ] }, "resource": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } }, { "description": "The resource which has triggered the event by being modified in some way." } ] }, "type": { "description": "*Deprecated: Refer to the resource_type of the resource.* The type of the resource that generated the event.", "type": "string", "readOnly": true, "example": "task" }, "action": { "description": "The type of action taken on the **resource** that triggered the event. This can be one of `changed`, `added`, `removed`, `deleted`, or `undeleted` depending on the nature of the event.", "type": "string", "readOnly": true, "example": "changed" }, "parent": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } }, { "description": "For added/removed events, the parent object that resource was added to or removed from. The parent will be `null` for other event types." } ] }, "created_at": { "description": "The timestamp when the event occurred.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "change": { "type": "object", "description": "Information about the type of change that has occurred. This field is only present when the value of the property `action`, describing the action taken on the **resource**, is `changed`.", "readOnly": true, "properties": { "field": { "description": "The name of the field that has changed in the resource.", "type": "string", "readOnly": true, "example": "assignee" }, "action": { "description": "The type of action taken on the **field** which has been changed. This can be one of `changed`, `added`, or `removed` depending on the nature of the change.", "type": "string", "readOnly": true, "example": "changed" }, "new_value": { "description": "*Conditional.* This property is only present when the value of the event's `change.action` is `changed` _and_ the `new_value` is an Asana resource. This will be only the `gid` and `resource_type` of the resource when the events come from webhooks; this will be the compact representation (and can have fields expanded with [opt_fields](/docs/inputoutput-options)) when using the [get events](/reference/getevents) endpoint.", "example": { "gid": "12345", "resource_type": "user" } }, "added_value": { "description": "*Conditional.* This property is only present when the value of the event's `change.action` is `added` _and_ the `added_value` is an Asana resource. This will be only the `gid` and `resource_type` of the resource when the events come from webhooks; this will be the compact representation (and can have fields expanded with [opt_fields](/docs/inputoutput-options)) when using the [get events](/reference/getevents) endpoint.", "example": { "gid": "12345", "resource_type": "user" } }, "removed_value": { "description": "*Conditional.* This property is only present when the value of the event's `change.action` is `removed` _and_ the `removed_value` is an Asana resource. This will be only the `gid` and `resource_type` of the resource when the events come from webhooks; this will be the compact representation (and can have fields expanded with [opt_fields](/docs/inputoutput-options)) when using the [get events](/reference/getevents) endpoint.", "example": { "gid": "12345", "resource_type": "user" } } } } } } }, "sync": { "description": "A sync token to be used with the next call to the /events endpoint.", "type": "string", "example": "de4774f6915eae04714ca93bb2f5ee81" }, "has_more": { "description": "Indicates whether there are more events to pull.", "type": "boolean", "example": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "description": "The request is missing or has an expired sync token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "readOnly": true, "description": "Message providing more detail about the error that occurred, if available.", "example": "Sync token invalid or too old. If you are attempting to keep resources in sync, you must fetch the full dataset for this query now and use the new sync token for the next sync." } } } }, "sync": { "type": "string", "readOnly": true, "description": "A sync token to be used with the next call to the /events endpoint.", "example": "de4774f6915eae04714ca93bb2f5ee81" } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.events.getEvents(sync, resource)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet eventsApiInstance = new Asana.EventsApi();\nlet resource = \"12345\"; // String | A resource ID to subscribe to. The resource can be a task, project, or goal.\nlet opts = { \n 'sync': \"de4774f6915eae04714ca93bb2f5ee81\", \n 'opt_fields': \"action,change,change.action,change.added_value,change.field,change.new_value,change.removed_value,created_at,parent,parent.name,resource,resource.name,type,user,user.name\"\n};\neventsApiInstance.getEvents(resource, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.events.getEvents({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nevents_api_instance = asana.EventsApi(api_client)\nresource = \"12345\" # str | A resource ID to subscribe to. The resource can be a task, project, or goal.\nopts = {\n 'sync': \"de4774f6915eae04714ca93bb2f5ee81\", # str | A sync token received from the last request, or none on first sync. Events will be returned from the point in time that the sync token was generated. *Note: On your first request, omit the sync token. The response will be the same as for an expired sync token, and will include a new valid sync token.If the sync token is too old (which may happen from time to time) the API will return a `412 Precondition Failed` error, and include a fresh sync token in the response.*\n 'opt_fields': \"action,change,change.action,change.added_value,change.field,change.new_value,change.removed_value,created_at,parent,parent.name,resource,resource.name,type,user,user.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get events on a resource\n api_response = events_api_instance.get_events(resource, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling EventsApi->get_events: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.events.get_events({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "events->getEvents(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.events.get_events(resource: ''resource_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/exports/graph": { "post": { "summary": "Initiate a graph export", "description": "Initiates a graph export job for a given parent object\n(goal, team, portfolio, or project). The export will be processed asynchronously.\nOnce initiated, use the [jobs](/reference/getjob) endpoint to monitor progress.\n\n**Export Caching:** When exporting more than 1,000 tasks, the results are cached for 4 hours. Any new export requests made within this 4-hour window will return the same cached results rather than generating a fresh export.", "tags": [ "Exports" ], "operationId": "createGraphExport", "requestBody": { "description": "A JSON payload specifying the parent object to export.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "A *graph_export* request starts a job to export data starting from a parent object.", "properties": { "parent": { "description": "Globally unique ID of the parent object: goal, project, portfolio, or team.", "type": "string", "example": "181636" } } } } } } } }, "responses": { "201": { "description": "Successfully created Graph export request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "job", "x-insert-after": "gid" }, "resource_subtype": { "description": "A *graph_export* object represents a request to export the data starting from a parent object", "type": "string", "readOnly": true, "example": "graph_export_request" }, "status": { "description": "The current status of this job.", "type": "string", "enum": [ "not_started", "in_progress", "succeeded", "failed" ], "readOnly": true, "example": "succeeded" }, "new_graph_export": { "description": "A *graph_export* object represents a request to export the data starting from a parent object", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "graph_export", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin JSON format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or\nfailed. If present, this URL may only be valid for 1 hour from\nthe time of retrieval. You should avoid persisting this URL\nsomewhere and rather refresh on demand to ensure you do not keep\nstale URLs.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/domain_export/7588024658887731/download/ domain_export_2563645399633793_7588024658887731_2023018-201726.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Content-Sha256=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host&x-id=GetObject#_=_" }, "completed_at": { "description": "The time at which this resource was completed.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet exportsApiInstance = new Asana.ExportsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | A JSON payload specifying the parent object to export.\n\nexportsApiInstance.createGraphExport(body).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nexports_api_instance = asana.ExportsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | A JSON payload specifying the parent object to export.\n\n\ntry:\n # Initiate a graph export\n api_response = exports_api_instance.create_graph_export(body)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ExportsApi->create_graph_export: %s\\n\" % e)", "name": "python-sdk-v5" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/exports/resource": { "post": { "summary": "Initiate a resource export", "description": "Initiates a bulk export of resources for a workspace. The export will be processed asynchronously. Once the export has been requested, its progress can be monitored using the [jobs](/reference/getjob) endpoint.\n\n## Supported resource types\nThis endpoint currently supports exporting tasks, teams and messages within a workspace. Resources can be requested to be part of the export by providing the `export_request_parameters` parameter. The following resource types are supported:\n\n### Tasks:\nTasks are formatted for exports with some differences from their documented [schema](/reference/tasks):\n - `attachments` are included by default and returns an array of associated attachments.\n - Attachment objects do not include `download_url` or `view_url`. The `attachments` [endpoint](/reference/attachment) should be queried for up-to-date URLs.\n - `stories` are included by default and returns an array of comments and other changes made to a task\n\n### Teams:\nTeams are formatted for exports with these differences from their documented [schema](/reference/teams):\n - `members` are included by default and returns an array of Users that are members of the team\n - Filtering is not supported for teams.\n\n### Messages:\nThe returned schema encompasses both default messages and status updates and is similar to the status update schema.\nThe available fields for messages are:\n - `gid` - The globally unique identifier for the message.\n - `resource_type` - The type of resource, which is always \"message\".\n - `resource_subtype` - Optional. The subtype of the message, which can be \"default\" or \"status_update\".\n - `status_type` - The type associated with the status update. This can be one of: \u201con_track\u201d, \u201cat_risk\u201d, \u201coff_track\u201d, \u201con_hold\u201d, \u201ccomplete\u201d, \u201cachieved\u201d, \u201cpartial\u201d, \u201cmissed\u201d, \u201cdropped\u201d\n - `created_by` - The user who created the message.\n - `created_at` - The time at which this resource was created and sent available to other users.\n - `modified_at` - The time at which this resource was last modified.\n - `title` - The title of the message.\n - `text` - The text content of the message.\n - `html_notes` - The text content of the message with formatting as HTML. Not included by default. Can be included by using \u201cfields\u201d in the initial request.\n - `num_likes` - The number of users who have liked this message.\n - `likes` - An array of users who have liked this message.\n - `stories` - Optional. Array of stories applied to the message.\n - `attachments` - Optional. Array of attachments added to the message.\n - `followers` - Optional. Array of users currently following the message. Users that were sent the message are treated as followers.\n - `parents` - Array of objects the message was sent to. Can be a Project, Portfolio, Team or Goal. Limited to a single object for status updates.\n\n\n## Export file\nThe final export file will be in JSON Lines format and compressed in a gzip container.\n\nObjects are formatted according to their corresponding API schema, or limited to the fields\nincluded in the `fields` parameter. Exports currently include undeleted objects.\n\nAn object in the export will be up to date anywhere between the exports `created_at` and `completed_at`. There is no guaranteed ordering of objects in the export.\n\nAccess to the export file expires 30 days after its completion.\n\n## Exporting specific fields\nBy default, each object in an export includes a predefined set of fields based on its schema. If a more limited set of fields\nor fields not included by default are required, the Export API allows for specifying which fields to include in the requested export.\n\nFields can be specified using the `fields` parameter. The fields parameter conforms to the fields\noptional parameter available for all Asana endpoints which is documented [here](https://developers.asana.com/docs/inputoutput-options).\n\nUtilizing the `fields` parameter is recommended if the full object is not required, especially when a large number of objects are being exported, to reduce the overall export time.\n\n## Filtering resources\nA disjunction of two or more filters can be achieved by providing multiple `export_request_parameters` for the same resource, each with different filters.\nHowever, this approach may result in duplicate resources being returned.\n\n## Rate Limits\nA workspace is currently limited to *one* in progress export request at a given time. The request will return with a 403 Forbidden status code if the limit is exceeded.", "tags": [ "Exports" ], "operationId": "createResourceExport", "requestBody": { "description": "A JSON payload specifying the resources to export, including filters to apply and fields to be exported.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "A *resource_export* request starts a job to bulk export objects for one or more resources.", "properties": { "workspace": { "type": "string", "description": "Gid of a workspace.", "example": "12345" }, "export_request_parameters": { "type": "array", "description": "An object containing the parameters for the export request. The keys of this object are the GIDs of the resources to be exported. The values are objects with additional parameters for each resource.", "items": { "type": "object", "properties": { "resource_type": { "type": "string", "description": "The type of the resource to be exported. This can be a task, team, or message.", "example": "task" }, "filters": { "type": "object", "description": "Filters to apply to a resource that will be exported. These filters can be used to narrow down the resources that are included in the export.", "properties": { "assigned_by.any": { "description": "Filter by the users who assigned the resource. This array accepts a list of user GIDs. This is only applicable to tasks.", "type": "array", "items": { "type": "string", "example": "12345" } }, "assignee.any": { "description": "Filter by the users who are assigned to the resource. This array accepts a list of user GIDs. This is only applicable to tasks.", "type": "array", "items": { "type": "string", "example": "12345" } }, "commented_on_by.any": { "description": "Filter by the users who commented on the resource. This array accepts a list of user GIDs.", "type": "array", "items": { "type": "string", "example": "12345" } }, "created_at.after": { "description": "Filter results to resources created after a specified date and time.", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "created_at.before": { "description": "Filter results to resources created before a specified date and time.", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "created_by.any": { "description": "Filter by the users who created the resource. This array accepts a list of user GIDs.", "type": "array", "items": { "type": "string", "example": "12345" } }, "followers.any": { "description": "Filter by the users who are following the resource. This array accepts a list of user GIDs.", "type": "array", "items": { "type": "string", "example": "12345" } }, "liked_by.any": { "description": "Filter by the users who liked the resource. This array accepts a list of user GIDs.", "type": "array", "items": { "type": "string", "example": "12345" } }, "modified_at.after": { "description": "Filter results to resources modified after a specified date and time.", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "modified_at.before": { "description": "Filter results to resources modified before a specified date and time.", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" } } }, "fields": { "type": "array", "description": "An array of fields to include for the resource type. If not provided, all non-optional fields for the resource type will be included. This conforms to the fields optional parameter available for all Asana endpoints which is documented [here](https://developers.asana.com/docs/inputoutput-options)", "items": { "type": "string", "example": "gid" } } } } } } } } } } } }, "responses": { "201": { "description": "Successfully created a Resource export request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "job", "x-insert-after": "gid" }, "resource_subtype": { "description": "A *resource_export* object represents a request to bulk export objects for one or more resources.", "type": "string", "readOnly": true, "example": "export_request" }, "status": { "description": "The current status of this job.", "type": "string", "enum": [ "not_started", "in_progress", "succeeded", "failed" ], "readOnly": true, "example": "succeeded" }, "new_resource_export": { "description": "A *resource_export* object represents a request to bulk export objects for one or more resources.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "export_request", "x-insert-after": "gid" }, "created_at": { "description": "The time at which the resource export object was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin [JSON Lines](https://jsonlines.org/) format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or failed.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/object_export/7588024658887731/download/ object_export_2563645399633793_7588024658887731_2023018-201726.jsonl.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Credential=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host" }, "completed_at": { "description": "The time at which this resource was completed. This will be null if the export is still in progress.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet exportsApiInstance = new Asana.ExportsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | A JSON payload specifying the resources to export, including filters to apply and fields to be exported.\n\nexportsApiInstance.createResourceExport(body).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nexports_api_instance = asana.ExportsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | A JSON payload specifying the resources to export, including filters to apply and fields to be exported.\n\n\ntry:\n # Initiate a resource export\n api_response = exports_api_instance.create_resource_export(body)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ExportsApi->create_resource_export: %s\\n\" % e)", "name": "python-sdk-v5" } ] }, "x-moar-primitive-count": 13, "x-moar-complexity-skipped": false } }, "/goal_relationships/{goal_relationship_gid}": { "parameters": [ { "name": "goal_relationship_gid", "in": "path", "description": "Globally unique identifier for the goal relationship.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "goal_relationship" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a goal relationship", "description": "Returns the complete updated goal relationship record for a single goal relationship.", "tags": [ "Goal relationships" ], "operationId": "getGoalRelationship", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "contribution_weight", "resource_subtype", "supported_goal", "supported_goal.name", "supported_goal.owner", "supported_goal.owner.name", "supporting_resource", "supporting_resource.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "contribution_weight", "resource_subtype", "supported_goal", "supported_goal.name", "supported_goal.owner", "supported_goal.owner.name", "supporting_resource", "supporting_resource.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the record for the goal relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *goal relationship* is an object representing the relationship between a goal and another goal, a project, a task, or a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal_relationship", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "subgoal", "enum": [ "subgoal", "supporting_work" ] }, "supporting_resource": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "readOnly": true, "description": "The supporting resource that supports the goal. This can be either a project, task, portfolio, or goal." } ] }, "contribution_weight": { "description": "The weight that the supporting resource's progress contributes to the supported goal's progress. This can be 0, 1, or any value in between.", "type": "number", "example": 1.0 } } }, { "type": "object", "properties": { "supported_goal": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } }, { "type": "object", "readOnly": true, "description": "The goal that the supporting resource supports." } ] } } } ] }, { "type": "object" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.goalrelationships.getGoalRelationship(goalRelationshipGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalRelationshipsApiInstance = new Asana.GoalRelationshipsApi();\nlet goal_relationship_gid = \"12345\"; // String | Globally unique identifier for the goal relationship.\nlet opts = { \n 'opt_fields': \"contribution_weight,resource_subtype,supported_goal,supported_goal.name,supported_goal.owner,supported_goal.owner.name,supporting_resource,supporting_resource.name\"\n};\ngoalRelationshipsApiInstance.getGoalRelationship(goal_relationship_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goalrelationships.getGoalRelationship(goalRelationshipGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoal_relationships_api_instance = asana.GoalRelationshipsApi(api_client)\ngoal_relationship_gid = \"12345\" # str | Globally unique identifier for the goal relationship.\nopts = {\n 'opt_fields': \"contribution_weight,resource_subtype,supported_goal,supported_goal.name,supported_goal.owner,supported_goal.owner.name,supporting_resource,supporting_resource.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a goal relationship\n api_response = goal_relationships_api_instance.get_goal_relationship(goal_relationship_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling GoalRelationshipsApi->get_goal_relationship: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goal_relationships.get_goal_relationship(goal_relationship_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goalrelationships->getGoalRelationship($goal_relationship_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goal_relationships.get_goal_relationship(goal_relationship_gid: 'goal_relationship_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a goal relationship", "description": "An existing goal relationship can be updated by making a PUT request on the URL for\nthat goal relationship. Only the fields provided in the `data` block will be updated;\nany unspecified fields will remain unchanged.\n\nReturns the complete updated goal relationship record.", "tags": [ "Goal relationships" ], "operationId": "updateGoalRelationship", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "contribution_weight", "resource_subtype", "supported_goal", "supported_goal.name", "supported_goal.owner", "supported_goal.owner.name", "supporting_resource", "supporting_resource.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "contribution_weight", "resource_subtype", "supported_goal", "supported_goal.name", "supported_goal.owner", "supported_goal.owner.name", "supporting_resource", "supporting_resource.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The updated fields for the goal relationship.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *goal relationship* is an object representing the relationship between a goal and another goal, a project, a task, or a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal_relationship", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "subgoal", "enum": [ "subgoal", "supporting_work" ] }, "supporting_resource": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "readOnly": true, "description": "The supporting resource that supports the goal. This can be either a project, task, portfolio, or goal." } ] }, "contribution_weight": { "description": "The weight that the supporting resource's progress contributes to the supported goal's progress. This can be 0, 1, or any value in between.", "type": "number", "example": 1.0 } } }, { "type": "object", "properties": { "supported_goal": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } }, { "type": "object", "readOnly": true, "description": "The goal that the supporting resource supports." } ] } } } ] }, { "type": "object" } ] } } } } } }, "responses": { "200": { "description": "Successfully updated the goal relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *goal relationship* is an object representing the relationship between a goal and another goal, a project, a task, or a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal_relationship", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "subgoal", "enum": [ "subgoal", "supporting_work" ] }, "supporting_resource": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "readOnly": true, "description": "The supporting resource that supports the goal. This can be either a project, task, portfolio, or goal." } ] }, "contribution_weight": { "description": "The weight that the supporting resource's progress contributes to the supported goal's progress. This can be 0, 1, or any value in between.", "type": "number", "example": 1.0 } } }, { "type": "object", "properties": { "supported_goal": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } }, { "type": "object", "readOnly": true, "description": "The goal that the supporting resource supports." } ] } } } ] }, { "type": "object" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.goalrelationships.updateGoalRelationship(goalRelationshipGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalRelationshipsApiInstance = new Asana.GoalRelationshipsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The updated fields for the goal relationship.\nlet goal_relationship_gid = \"12345\"; // String | Globally unique identifier for the goal relationship.\nlet opts = { \n 'opt_fields': \"contribution_weight,resource_subtype,supported_goal,supported_goal.name,supported_goal.owner,supported_goal.owner.name,supporting_resource,supporting_resource.name\"\n};\ngoalRelationshipsApiInstance.updateGoalRelationship(body, goal_relationship_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goalrelationships.updateGoalRelationship(goalRelationshipGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoal_relationships_api_instance = asana.GoalRelationshipsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The updated fields for the goal relationship.\ngoal_relationship_gid = \"12345\" # str | Globally unique identifier for the goal relationship.\nopts = {\n 'opt_fields': \"contribution_weight,resource_subtype,supported_goal,supported_goal.name,supported_goal.owner,supported_goal.owner.name,supporting_resource,supporting_resource.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a goal relationship\n api_response = goal_relationships_api_instance.update_goal_relationship(body, goal_relationship_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling GoalRelationshipsApi->update_goal_relationship: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goal_relationships.update_goal_relationship(goal_relationship_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goalrelationships->updateGoalRelationship($goal_relationship_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goal_relationships.update_goal_relationship(goal_relationship_gid: 'goal_relationship_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 13, "x-moar-complexity-skipped": false } }, "/goal_relationships": { "get": { "summary": "Get goal relationships", "description": "Returns compact goal relationship records.", "tags": [ "Goal relationships" ], "operationId": "getGoalRelationships", "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "supported_goal", "required": true, "in": "query", "description": "Globally unique identifier for the supported goal in the goal relationship.", "schema": { "type": "string" }, "example": "12345" }, { "name": "resource_subtype", "in": "query", "description": "If provided, filter to goal relationships with a given resource_subtype.", "schema": { "type": "string" }, "example": "subgoal" }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "contribution_weight", "offset", "path", "resource_subtype", "supported_goal", "supported_goal.name", "supported_goal.owner", "supported_goal.owner.name", "supporting_resource", "supporting_resource.name", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "contribution_weight", "offset", "path", "resource_subtype", "supported_goal", "supported_goal.name", "supported_goal.owner", "supported_goal.owner.name", "supporting_resource", "supporting_resource.name", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested goal relationships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *goal relationship* is an object representing the relationship between a goal and another goal, a project, a task, or a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal_relationship", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "subgoal", "enum": [ "subgoal", "supporting_work" ] }, "supporting_resource": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "readOnly": true, "description": "The supporting resource that supports the goal. This can be either a project, task, portfolio, or goal." } ] }, "contribution_weight": { "description": "The weight that the supporting resource's progress contributes to the supported goal's progress. This can be 0, 1, or any value in between.", "type": "number", "example": 1.0 } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.goalrelationships.getGoalRelationships(resourceSubtype, supportedGoal)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalRelationshipsApiInstance = new Asana.GoalRelationshipsApi();\nlet supported_goal = \"12345\"; // String | Globally unique identifier for the supported goal in the goal relationship.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'resource_subtype': \"subgoal\", \n 'opt_fields': \"contribution_weight,offset,path,resource_subtype,supported_goal,supported_goal.name,supported_goal.owner,supported_goal.owner.name,supporting_resource,supporting_resource.name,uri\"\n};\ngoalRelationshipsApiInstance.getGoalRelationships(supported_goal, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goalrelationships.getGoalRelationships({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoal_relationships_api_instance = asana.GoalRelationshipsApi(api_client)\nsupported_goal = \"12345\" # str | Globally unique identifier for the supported goal in the goal relationship.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'resource_subtype': \"subgoal\", # str | If provided, filter to goal relationships with a given resource_subtype.\n 'opt_fields': \"contribution_weight,offset,path,resource_subtype,supported_goal,supported_goal.name,supported_goal.owner,supported_goal.owner.name,supporting_resource,supporting_resource.name,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get goal relationships\n api_response = goal_relationships_api_instance.get_goal_relationships(supported_goal, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling GoalRelationshipsApi->get_goal_relationships: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goal_relationships.get_goal_relationships({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goalrelationships->getGoalRelationships(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goal_relationships.get_goal_relationships(supported_goal: ''supported_goal_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/goals/{goal_gid}/addSupportingRelationship": { "parameters": [ { "name": "goal_gid", "in": "path", "description": "Globally unique identifier for the goal.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "goal" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add a supporting goal relationship", "description": "Creates a goal relationship by adding a supporting resource to a given goal.\n\nReturns the newly created goal relationship record.", "tags": [ "Goal relationships" ], "operationId": "addSupportingRelationship", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "contribution_weight", "resource_subtype", "supported_goal", "supported_goal.name", "supported_goal.owner", "supported_goal.owner.name", "supporting_resource", "supporting_resource.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "contribution_weight", "resource_subtype", "supported_goal", "supported_goal.name", "supported_goal.owner", "supported_goal.owner.name", "supporting_resource", "supporting_resource.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The supporting resource to be added to the goal", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "supporting_resource" ], "properties": { "supporting_resource": { "description": "The gid of the supporting resource to add to the parent goal. Must be the gid of a goal, project, task, or portfolio.", "type": "string", "example": "12345" }, "insert_before": { "description": "An id of a subgoal of this parent goal. The new subgoal will be added before the one specified here. `insert_before` and `insert_after` parameters cannot both be specified. Currently only supported when adding a subgoal.", "type": "string", "example": "1331" }, "insert_after": { "description": "An id of a subgoal of this parent goal. The new subgoal will be added after the one specified here. `insert_before` and `insert_after` parameters cannot both be specified. Currently only supported when adding a subgoal.", "type": "string", "example": "1331" }, "contribution_weight": { "description": "Defines how much the supporting goal\u2019s progress contributes to the parent goal\u2019s overall progress. When used with automatically calculated [Goal Metrics](/reference/creategoalmetric) (such as `progress_source = subgoal_progress`), this value must be greater than 0 for the subgoal to count toward the parent goal\u2019s progress.\nAccepts a number between 0 and 1 (inclusive). Defaults to `0`.", "type": "number", "example": 0 } } } } } } } }, "responses": { "200": { "description": "Successfully created the goal relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *goal relationship* is an object representing the relationship between a goal and another goal, a project, a task, or a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal_relationship", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "subgoal", "enum": [ "subgoal", "supporting_work" ] }, "supporting_resource": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "readOnly": true, "description": "The supporting resource that supports the goal. This can be either a project, task, portfolio, or goal." } ] }, "contribution_weight": { "description": "The weight that the supporting resource's progress contributes to the supported goal's progress. This can be 0, 1, or any value in between.", "type": "number", "example": 1.0 } } }, { "type": "object", "properties": { "supported_goal": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } }, { "type": "object", "readOnly": true, "description": "The goal that the supporting resource supports." } ] } } } ] }, { "type": "object" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.goalrelationships.addSupportingRelationship(goalGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalRelationshipsApiInstance = new Asana.GoalRelationshipsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The supporting resource to be added to the goal\nlet goal_gid = \"12345\"; // String | Globally unique identifier for the goal.\nlet opts = { \n 'opt_fields': \"contribution_weight,resource_subtype,supported_goal,supported_goal.name,supported_goal.owner,supported_goal.owner.name,supporting_resource,supporting_resource.name\"\n};\ngoalRelationshipsApiInstance.addSupportingRelationship(body, goal_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goalrelationships.addSupportingRelationship(goalGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoal_relationships_api_instance = asana.GoalRelationshipsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The supporting resource to be added to the goal\ngoal_gid = \"12345\" # str | Globally unique identifier for the goal.\nopts = {\n 'opt_fields': \"contribution_weight,resource_subtype,supported_goal,supported_goal.name,supported_goal.owner,supported_goal.owner.name,supporting_resource,supporting_resource.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Add a supporting goal relationship\n api_response = goal_relationships_api_instance.add_supporting_relationship(body, goal_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling GoalRelationshipsApi->add_supporting_relationship: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goal_relationships.add_supporting_relationship(goal_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goalrelationships->addSupportingRelationship($goal_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goal_relationships.add_supporting_relationship(goal_gid: 'goal_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 4, "x-moar-complexity-skipped": false } }, "/goals/{goal_gid}/removeSupportingRelationship": { "parameters": [ { "name": "goal_gid", "in": "path", "description": "Globally unique identifier for the goal.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "goal" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Removes a supporting goal relationship", "description": "Removes a goal relationship for a given parent goal.", "tags": [ "Goal relationships" ], "operationId": "removeSupportingRelationship", "requestBody": { "description": "The supporting resource to be removed from the goal", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "supporting_resource" ], "properties": { "supporting_resource": { "description": "The gid of the supporting resource to remove from the parent goal. Must be the gid of a goal, project, task, or portfolio.", "type": "string", "example": "12345" } } } } } } } }, "responses": { "200": { "description": "Successfully removed the goal relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.goalrelationships.removeSupportingRelationship(goalGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalRelationshipsApiInstance = new Asana.GoalRelationshipsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The supporting resource to be removed from the goal\nlet goal_gid = \"12345\"; // String | Globally unique identifier for the goal.\n\ngoalRelationshipsApiInstance.removeSupportingRelationship(body, goal_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goalrelationships.removeSupportingRelationship(goalGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoal_relationships_api_instance = asana.GoalRelationshipsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The supporting resource to be removed from the goal\ngoal_gid = \"12345\" # str | Globally unique identifier for the goal.\n\n\ntry:\n # Removes a supporting goal relationship\n api_response = goal_relationships_api_instance.remove_supporting_relationship(body, goal_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling GoalRelationshipsApi->remove_supporting_relationship: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goal_relationships.remove_supporting_relationship(goal_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goalrelationships->removeSupportingRelationship($goal_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goal_relationships.remove_supporting_relationship(goal_gid: 'goal_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/goals/{goal_gid}": { "parameters": [ { "name": "goal_gid", "in": "path", "description": "Globally unique identifier for the goal.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "goal" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a goal", "description": "Required scope: goals:read\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
FieldRequired Scope
time_periodtime_periods:read
custom_field_settingscustom_fields:read
\n\nReturns the complete goal record for a single goal.", "tags": [ "Goals" ], "operationId": "getGoal", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the record for a single goal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "html_notes": { "type": "string", "description": "The notes of the goal with formatting as HTML.", "example": "Start building brand awareness." }, "notes": { "type": "string", "description": "Free-form textual information associated with the goal (i.e. its description).", "example": "Start building brand awareness." }, "due_on": { "type": "string", "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "example": "2019-09-15", "nullable": true }, "start_on": { "type": "string", "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "example": "2019-09-14", "nullable": true }, "is_workspace_level": { "type": "boolean", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization. Whether the goal belongs to the `workspace` (and is listed as part of the workspace\u2019s goals) or not. If it isn\u2019t a workspace-level goal, it is a team-level goal, and is associated with the goal\u2019s team.", "example": true }, "liked": { "type": "boolean", "description": "True if the goal is liked by the authorized user, false if not.", "example": false } } }, { "type": "object", "properties": { "likes": { "description": "Array of likes for users who have liked this goal.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this goal.", "type": "integer", "readOnly": true, "example": 5 }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when the `workspace` provided is an organization." } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object" } ] }, "followers": { "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "description": "Array of users who are members of this goal." }, "time_period": { "allOf": [ { "description": "

Full object requires scope: time_periods:read

\n\nA generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_period", "x-insert-after": "gid" }, "end_on": { "type": "string", "description": "The localized end date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-14" }, "start_on": { "type": "string", "description": "The localized start date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-13" }, "period": { "type": "string", "description": "The cadence and index of the time period.", "enum": [ "FY", "H1", "H2", "Q1", "Q2", "Q3", "Q4" ], "example": "Q1" }, "display_name": { "type": "string", "description": "A string representing the cadence code and the fiscal year.", "example": "Q1 FY22" } } }, { "type": "object", "nullable": true } ] }, "metric": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "number", "enum": [ "number" ] }, "precision": { "description": "*Conditional*. Only relevant for goal metrics of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.", "type": "integer", "example": 2 }, "unit": { "description": "A supported unit of measure for the goal metric, or none.", "type": "string", "enum": [ "none", "currency", "percentage" ] }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "initial_number_value": { "description": "This number is the start value of a goal metric of type number.", "type": "number", "example": 5.2 }, "target_number_value": { "description": "This number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`.", "type": "number", "example": 10.2 }, "current_number_value": { "description": "This number is the current value of a goal metric of type number.", "type": "number", "example": 8.12 }, "current_display_value": { "description": "This string is the current value of a goal metric of type string.", "type": "string", "readOnly": true, "example": "8.12" }, "progress_source": { "description": "This field defines how the progress value of a goal metric is being calculated. A goal's progress can be provided manually by the user, calculated automatically from contributing subgoals, projects, or tasks, or managed by an integration with an external data source, such as Salesforce.", "type": "string", "enum": [ "manual", "subgoal_progress", "project_task_completion", "project_milestone_completion", "task_completion", "external" ], "example": "manual" }, "is_custom_weight": { "description": "*Conditional*. Only relevant if `metric.progress_source` is one of `subgoal_progress`, `project_task_completion`, `project_milestone_completion`, or `task_completion`. If true, we use the supporting object's custom weight to calculate the goal's progress. If false, we treat all supporting objects as equally weighted", "type": "boolean", "example": false } } }, { "type": "object", "nullable": true, "properties": { "can_manage": { "description": "*Conditional*. Only relevant for `progress_source` of type `external`. This boolean indicates whether the requester has the ability to update the current value of this metric. This returns `true` if the external metric was created by the requester, `false` otherwise.", "type": "boolean", "readOnly": true, "example": true } } } ] }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "description": "The latest `status_update` posted to this goal.", "nullable": true } ] }, "status": { "type": "string", "readOnly": true, "description": "The current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect \"On Track\", \"At Risk\", and \"Off Track\", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.\n*Note* you can only write to this property if `metric` is set.", "example": "green", "nullable": true } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "goals:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.goals.getGoal(goalGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalsApiInstance = new Asana.GoalsApi();\nlet goal_gid = \"12345\"; // String | Globally unique identifier for the goal.\nlet opts = { \n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\"\n};\ngoalsApiInstance.getGoal(goal_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goals.getGoal(goalGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoals_api_instance = asana.GoalsApi(api_client)\ngoal_gid = \"12345\" # str | Globally unique identifier for the goal.\nopts = {\n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a goal\n api_response = goals_api_instance.get_goal(goal_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling GoalsApi->get_goal: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goals.get_goal(goal_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goals->getGoal($goal_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goals.get_goal(goal_gid: 'goal_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a goal", "description": "An existing goal can be updated by making a PUT request on the URL for\nthat goal. Only the fields provided in the `data` block will be updated;\nany unspecified fields will remain unchanged.\n\nReturns the complete updated goal record.", "tags": [ "Goals" ], "operationId": "updateGoal", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The updated fields for the goal.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "html_notes": { "type": "string", "description": "The notes of the goal with formatting as HTML.", "example": "Start building brand awareness." }, "notes": { "type": "string", "description": "Free-form textual information associated with the goal (i.e. its description).", "example": "Start building brand awareness." }, "due_on": { "type": "string", "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "example": "2019-09-15", "nullable": true }, "start_on": { "type": "string", "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "example": "2019-09-14", "nullable": true }, "is_workspace_level": { "type": "boolean", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization. Whether the goal belongs to the `workspace` (and is listed as part of the workspace\u2019s goals) or not. If it isn\u2019t a workspace-level goal, it is a team-level goal, and is associated with the goal\u2019s team.", "example": true }, "liked": { "type": "boolean", "description": "True if the goal is liked by the authorized user, false if not.", "example": false } } }, { "type": "object", "properties": { "team": { "type": "string", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization.", "example": "12345", "nullable": true }, "workspace": { "type": "string", "description": "The `gid` of a workspace.", "example": "12345" }, "time_period": { "type": "string", "description": "The `gid` of a time period.", "example": "12345", "nullable": true }, "owner": { "type": "string", "description": "The `gid` of a user.", "example": "12345", "nullable": true } } } ] }, { "type": "object", "properties": { "status": { "type": "string", "description": "The current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect \"On Track\", \"At Risk\", and \"Off Track\", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.\n*Note* you can only write to this property if `metric` is set.", "example": "green", "nullable": true } } } ] } } } } } }, "responses": { "200": { "description": "Successfully updated the goal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "html_notes": { "type": "string", "description": "The notes of the goal with formatting as HTML.", "example": "Start building brand awareness." }, "notes": { "type": "string", "description": "Free-form textual information associated with the goal (i.e. its description).", "example": "Start building brand awareness." }, "due_on": { "type": "string", "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "example": "2019-09-15", "nullable": true }, "start_on": { "type": "string", "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "example": "2019-09-14", "nullable": true }, "is_workspace_level": { "type": "boolean", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization. Whether the goal belongs to the `workspace` (and is listed as part of the workspace\u2019s goals) or not. If it isn\u2019t a workspace-level goal, it is a team-level goal, and is associated with the goal\u2019s team.", "example": true }, "liked": { "type": "boolean", "description": "True if the goal is liked by the authorized user, false if not.", "example": false } } }, { "type": "object", "properties": { "likes": { "description": "Array of likes for users who have liked this goal.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this goal.", "type": "integer", "readOnly": true, "example": 5 }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when the `workspace` provided is an organization." } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object" } ] }, "followers": { "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "description": "Array of users who are members of this goal." }, "time_period": { "allOf": [ { "description": "

Full object requires scope: time_periods:read

\n\nA generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_period", "x-insert-after": "gid" }, "end_on": { "type": "string", "description": "The localized end date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-14" }, "start_on": { "type": "string", "description": "The localized start date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-13" }, "period": { "type": "string", "description": "The cadence and index of the time period.", "enum": [ "FY", "H1", "H2", "Q1", "Q2", "Q3", "Q4" ], "example": "Q1" }, "display_name": { "type": "string", "description": "A string representing the cadence code and the fiscal year.", "example": "Q1 FY22" } } }, { "type": "object", "nullable": true } ] }, "metric": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "number", "enum": [ "number" ] }, "precision": { "description": "*Conditional*. Only relevant for goal metrics of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.", "type": "integer", "example": 2 }, "unit": { "description": "A supported unit of measure for the goal metric, or none.", "type": "string", "enum": [ "none", "currency", "percentage" ] }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "initial_number_value": { "description": "This number is the start value of a goal metric of type number.", "type": "number", "example": 5.2 }, "target_number_value": { "description": "This number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`.", "type": "number", "example": 10.2 }, "current_number_value": { "description": "This number is the current value of a goal metric of type number.", "type": "number", "example": 8.12 }, "current_display_value": { "description": "This string is the current value of a goal metric of type string.", "type": "string", "readOnly": true, "example": "8.12" }, "progress_source": { "description": "This field defines how the progress value of a goal metric is being calculated. A goal's progress can be provided manually by the user, calculated automatically from contributing subgoals, projects, or tasks, or managed by an integration with an external data source, such as Salesforce.", "type": "string", "enum": [ "manual", "subgoal_progress", "project_task_completion", "project_milestone_completion", "task_completion", "external" ], "example": "manual" }, "is_custom_weight": { "description": "*Conditional*. Only relevant if `metric.progress_source` is one of `subgoal_progress`, `project_task_completion`, `project_milestone_completion`, or `task_completion`. If true, we use the supporting object's custom weight to calculate the goal's progress. If false, we treat all supporting objects as equally weighted", "type": "boolean", "example": false } } }, { "type": "object", "nullable": true, "properties": { "can_manage": { "description": "*Conditional*. Only relevant for `progress_source` of type `external`. This boolean indicates whether the requester has the ability to update the current value of this metric. This returns `true` if the external metric was created by the requester, `false` otherwise.", "type": "boolean", "readOnly": true, "example": true } } } ] }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "description": "The latest `status_update` posted to this goal.", "nullable": true } ] }, "status": { "type": "string", "readOnly": true, "description": "The current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect \"On Track\", \"At Risk\", and \"Off Track\", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.\n*Note* you can only write to this property if `metric` is set.", "example": "green", "nullable": true } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.goals.updateGoal(goalGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalsApiInstance = new Asana.GoalsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The updated fields for the goal.\nlet goal_gid = \"12345\"; // String | Globally unique identifier for the goal.\nlet opts = { \n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\"\n};\ngoalsApiInstance.updateGoal(body, goal_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goals.updateGoal(goalGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoals_api_instance = asana.GoalsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The updated fields for the goal.\ngoal_gid = \"12345\" # str | Globally unique identifier for the goal.\nopts = {\n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a goal\n api_response = goals_api_instance.update_goal(body, goal_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling GoalsApi->update_goal: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goals.update_goal(goal_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goals->updateGoal($goal_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goals.update_goal(goal_gid: 'goal_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 14, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a goal", "description": "A specific, existing goal can be deleted by making a DELETE request on the URL for that goal.\n\nReturns an empty data record.", "tags": [ "Goals" ], "operationId": "deleteGoal", "responses": { "200": { "description": "Successfully deleted the specified goal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.goals.deleteGoal(goalGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalsApiInstance = new Asana.GoalsApi();\nlet goal_gid = \"12345\"; // String | Globally unique identifier for the goal.\n\ngoalsApiInstance.deleteGoal(goal_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goals.deleteGoal(goalGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoals_api_instance = asana.GoalsApi(api_client)\ngoal_gid = \"12345\" # str | Globally unique identifier for the goal.\n\n\ntry:\n # Delete a goal\n api_response = goals_api_instance.delete_goal(goal_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling GoalsApi->delete_goal: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goals.delete_goal(goal_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goals->deleteGoal($goal_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goals.delete_goal(goal_gid: 'goal_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/goals": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get goals", "description": "Required scope: goals:read\n\nReturns compact goal records.", "tags": [ "Goals" ], "operationId": "getGoals", "parameters": [ { "name": "portfolio", "in": "query", "description": "Globally unique identifier for supporting portfolio.", "schema": { "type": "string" }, "example": "159874" }, { "name": "project", "in": "query", "description": "Globally unique identifier for supporting project.", "schema": { "type": "string" }, "example": "512241" }, { "name": "task", "in": "query", "description": "Globally unique identifier for supporting task.", "schema": { "type": "string" }, "example": "78424" }, { "name": "is_workspace_level", "in": "query", "description": "Filter to goals with is_workspace_level set to query value. Must be used with the workspace parameter.", "schema": { "type": "boolean" }, "example": false }, { "name": "team", "in": "query", "description": "Globally unique identifier for the team.", "schema": { "type": "string" }, "example": "31326" }, { "name": "workspace", "in": "query", "description": "Globally unique identifier for the workspace.", "schema": { "type": "string" }, "example": "31326" }, { "name": "time_periods", "in": "query", "description": "Globally unique identifiers for the time periods.", "schema": { "type": "array", "items": { "type": "string" } }, "example": "221693,506165" }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "offset", "owner", "owner.name", "path", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "offset", "owner", "owner.name", "path", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested goals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "goals:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.goals.getGoals(timePeriods, workspace, team, isWorkspaceLevel, project, portfolio)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalsApiInstance = new Asana.GoalsApi();\nlet opts = { \n 'portfolio': \"159874\", \n 'project': \"512241\", \n 'task': \"78424\", \n 'is_workspace_level': false, \n 'team': \"31326\", \n 'workspace': \"31326\", \n 'time_periods': \"221693,506165\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,offset,owner,owner.name,path,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,uri,workspace,workspace.name\"\n};\ngoalsApiInstance.getGoals(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goals.getGoals({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoals_api_instance = asana.GoalsApi(api_client)\nopts = {\n 'portfolio': \"159874\", # str | Globally unique identifier for supporting portfolio.\n 'project': \"512241\", # str | Globally unique identifier for supporting project.\n 'task': \"78424\", # str | Globally unique identifier for supporting task.\n 'is_workspace_level': False, # bool | Filter to goals with is_workspace_level set to query value. Must be used with the workspace parameter.\n 'team': \"31326\", # str | Globally unique identifier for the team.\n 'workspace': \"31326\", # str | Globally unique identifier for the workspace.\n 'time_periods': \"221693,506165\", # list[str] | Globally unique identifiers for the time periods.\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,offset,owner,owner.name,path,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get goals\n api_response = goals_api_instance.get_goals(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling GoalsApi->get_goals: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goals.get_goals({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goals->getGoals(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goals.get_goals(param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a goal", "description": "Creates a new goal in a workspace or team.\n\nReturns the full record of the newly created goal.", "tags": [ "Goals" ], "operationId": "createGoal", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The goal to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "html_notes": { "type": "string", "description": "The notes of the goal with formatting as HTML.", "example": "Start building brand awareness." }, "notes": { "type": "string", "description": "Free-form textual information associated with the goal (i.e. its description).", "example": "Start building brand awareness." }, "due_on": { "type": "string", "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "example": "2019-09-15", "nullable": true }, "start_on": { "type": "string", "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "example": "2019-09-14", "nullable": true }, "is_workspace_level": { "type": "boolean", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization. Whether the goal belongs to the `workspace` (and is listed as part of the workspace\u2019s goals) or not. If it isn\u2019t a workspace-level goal, it is a team-level goal, and is associated with the goal\u2019s team.", "example": true }, "liked": { "type": "boolean", "description": "True if the goal is liked by the authorized user, false if not.", "example": false } } }, { "type": "object", "properties": { "team": { "type": "string", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization.", "example": "12345", "nullable": true }, "workspace": { "type": "string", "description": "The `gid` of a workspace.", "example": "12345" }, "time_period": { "type": "string", "description": "The `gid` of a time period.", "example": "12345", "nullable": true }, "owner": { "type": "string", "description": "The `gid` of a user.", "example": "12345", "nullable": true } } } ] }, { "type": "object", "properties": { "followers": { "type": "array", "items": { "type": "string", "description": "The `gid` of a user." }, "example": [ "12345" ] } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created a new goal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "html_notes": { "type": "string", "description": "The notes of the goal with formatting as HTML.", "example": "Start building brand awareness." }, "notes": { "type": "string", "description": "Free-form textual information associated with the goal (i.e. its description).", "example": "Start building brand awareness." }, "due_on": { "type": "string", "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "example": "2019-09-15", "nullable": true }, "start_on": { "type": "string", "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "example": "2019-09-14", "nullable": true }, "is_workspace_level": { "type": "boolean", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization. Whether the goal belongs to the `workspace` (and is listed as part of the workspace\u2019s goals) or not. If it isn\u2019t a workspace-level goal, it is a team-level goal, and is associated with the goal\u2019s team.", "example": true }, "liked": { "type": "boolean", "description": "True if the goal is liked by the authorized user, false if not.", "example": false } } }, { "type": "object", "properties": { "likes": { "description": "Array of likes for users who have liked this goal.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this goal.", "type": "integer", "readOnly": true, "example": 5 }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when the `workspace` provided is an organization." } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object" } ] }, "followers": { "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "description": "Array of users who are members of this goal." }, "time_period": { "allOf": [ { "description": "

Full object requires scope: time_periods:read

\n\nA generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_period", "x-insert-after": "gid" }, "end_on": { "type": "string", "description": "The localized end date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-14" }, "start_on": { "type": "string", "description": "The localized start date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-13" }, "period": { "type": "string", "description": "The cadence and index of the time period.", "enum": [ "FY", "H1", "H2", "Q1", "Q2", "Q3", "Q4" ], "example": "Q1" }, "display_name": { "type": "string", "description": "A string representing the cadence code and the fiscal year.", "example": "Q1 FY22" } } }, { "type": "object", "nullable": true } ] }, "metric": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "number", "enum": [ "number" ] }, "precision": { "description": "*Conditional*. Only relevant for goal metrics of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.", "type": "integer", "example": 2 }, "unit": { "description": "A supported unit of measure for the goal metric, or none.", "type": "string", "enum": [ "none", "currency", "percentage" ] }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "initial_number_value": { "description": "This number is the start value of a goal metric of type number.", "type": "number", "example": 5.2 }, "target_number_value": { "description": "This number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`.", "type": "number", "example": 10.2 }, "current_number_value": { "description": "This number is the current value of a goal metric of type number.", "type": "number", "example": 8.12 }, "current_display_value": { "description": "This string is the current value of a goal metric of type string.", "type": "string", "readOnly": true, "example": "8.12" }, "progress_source": { "description": "This field defines how the progress value of a goal metric is being calculated. A goal's progress can be provided manually by the user, calculated automatically from contributing subgoals, projects, or tasks, or managed by an integration with an external data source, such as Salesforce.", "type": "string", "enum": [ "manual", "subgoal_progress", "project_task_completion", "project_milestone_completion", "task_completion", "external" ], "example": "manual" }, "is_custom_weight": { "description": "*Conditional*. Only relevant if `metric.progress_source` is one of `subgoal_progress`, `project_task_completion`, `project_milestone_completion`, or `task_completion`. If true, we use the supporting object's custom weight to calculate the goal's progress. If false, we treat all supporting objects as equally weighted", "type": "boolean", "example": false } } }, { "type": "object", "nullable": true, "properties": { "can_manage": { "description": "*Conditional*. Only relevant for `progress_source` of type `external`. This boolean indicates whether the requester has the ability to update the current value of this metric. This returns `true` if the external metric was created by the requester, `false` otherwise.", "type": "boolean", "readOnly": true, "example": true } } } ] }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "description": "The latest `status_update` posted to this goal.", "nullable": true } ] }, "status": { "type": "string", "readOnly": true, "description": "The current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect \"On Track\", \"At Risk\", and \"Off Track\", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.\n*Note* you can only write to this property if `metric` is set.", "example": "green", "nullable": true } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.goals.createGoal()\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalsApiInstance = new Asana.GoalsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The goal to create.\nlet opts = { \n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\"\n};\ngoalsApiInstance.createGoal(body, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goals.createGoal({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoals_api_instance = asana.GoalsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The goal to create.\nopts = {\n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a goal\n api_response = goals_api_instance.create_goal(body, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling GoalsApi->create_goal: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goals.create_goal({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goals->createGoal(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goals.create_goal(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 14, "x-moar-complexity-skipped": false } }, "/goals/{goal_gid}/setMetric": { "parameters": [ { "name": "goal_gid", "in": "path", "description": "Globally unique identifier for the goal.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "goal" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Create a goal metric", "description": "Creates and adds a goal metric to a specified goal. Note that this replaces an existing goal metric if one already exists.", "tags": [ "Goals" ], "operationId": "createGoalMetric", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The goal metric to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "number", "enum": [ "number" ] }, "precision": { "description": "*Conditional*. Only relevant for goal metrics of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.", "type": "integer", "example": 2 }, "unit": { "description": "A supported unit of measure for the goal metric, or none.", "type": "string", "enum": [ "none", "currency", "percentage" ] }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "initial_number_value": { "description": "This number is the start value of a goal metric of type number.", "type": "number", "example": 5.2 }, "target_number_value": { "description": "This number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`.", "type": "number", "example": 10.2 }, "current_number_value": { "description": "This number is the current value of a goal metric of type number.", "type": "number", "example": 8.12 }, "current_display_value": { "description": "This string is the current value of a goal metric of type string.", "type": "string", "readOnly": true, "example": "8.12" }, "progress_source": { "description": "This field defines how the progress value of a goal metric is being calculated. A goal's progress can be provided manually by the user, calculated automatically from contributing subgoals, projects, or tasks, or managed by an integration with an external data source, such as Salesforce.", "type": "string", "enum": [ "manual", "subgoal_progress", "project_task_completion", "project_milestone_completion", "task_completion", "external" ], "example": "manual" }, "is_custom_weight": { "description": "*Conditional*. Only relevant if `metric.progress_source` is one of `subgoal_progress`, `project_task_completion`, `project_milestone_completion`, or `task_completion`. If true, we use the supporting object's custom weight to calculate the goal's progress. If false, we treat all supporting objects as equally weighted", "type": "boolean", "example": false } } } } } } } }, "responses": { "200": { "description": "Successfully created a new goal metric.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "html_notes": { "type": "string", "description": "The notes of the goal with formatting as HTML.", "example": "Start building brand awareness." }, "notes": { "type": "string", "description": "Free-form textual information associated with the goal (i.e. its description).", "example": "Start building brand awareness." }, "due_on": { "type": "string", "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "example": "2019-09-15", "nullable": true }, "start_on": { "type": "string", "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "example": "2019-09-14", "nullable": true }, "is_workspace_level": { "type": "boolean", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization. Whether the goal belongs to the `workspace` (and is listed as part of the workspace\u2019s goals) or not. If it isn\u2019t a workspace-level goal, it is a team-level goal, and is associated with the goal\u2019s team.", "example": true }, "liked": { "type": "boolean", "description": "True if the goal is liked by the authorized user, false if not.", "example": false } } }, { "type": "object", "properties": { "likes": { "description": "Array of likes for users who have liked this goal.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this goal.", "type": "integer", "readOnly": true, "example": 5 }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when the `workspace` provided is an organization." } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object" } ] }, "followers": { "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "description": "Array of users who are members of this goal." }, "time_period": { "allOf": [ { "description": "

Full object requires scope: time_periods:read

\n\nA generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_period", "x-insert-after": "gid" }, "end_on": { "type": "string", "description": "The localized end date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-14" }, "start_on": { "type": "string", "description": "The localized start date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-13" }, "period": { "type": "string", "description": "The cadence and index of the time period.", "enum": [ "FY", "H1", "H2", "Q1", "Q2", "Q3", "Q4" ], "example": "Q1" }, "display_name": { "type": "string", "description": "A string representing the cadence code and the fiscal year.", "example": "Q1 FY22" } } }, { "type": "object", "nullable": true } ] }, "metric": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "number", "enum": [ "number" ] }, "precision": { "description": "*Conditional*. Only relevant for goal metrics of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.", "type": "integer", "example": 2 }, "unit": { "description": "A supported unit of measure for the goal metric, or none.", "type": "string", "enum": [ "none", "currency", "percentage" ] }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "initial_number_value": { "description": "This number is the start value of a goal metric of type number.", "type": "number", "example": 5.2 }, "target_number_value": { "description": "This number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`.", "type": "number", "example": 10.2 }, "current_number_value": { "description": "This number is the current value of a goal metric of type number.", "type": "number", "example": 8.12 }, "current_display_value": { "description": "This string is the current value of a goal metric of type string.", "type": "string", "readOnly": true, "example": "8.12" }, "progress_source": { "description": "This field defines how the progress value of a goal metric is being calculated. A goal's progress can be provided manually by the user, calculated automatically from contributing subgoals, projects, or tasks, or managed by an integration with an external data source, such as Salesforce.", "type": "string", "enum": [ "manual", "subgoal_progress", "project_task_completion", "project_milestone_completion", "task_completion", "external" ], "example": "manual" }, "is_custom_weight": { "description": "*Conditional*. Only relevant if `metric.progress_source` is one of `subgoal_progress`, `project_task_completion`, `project_milestone_completion`, or `task_completion`. If true, we use the supporting object's custom weight to calculate the goal's progress. If false, we treat all supporting objects as equally weighted", "type": "boolean", "example": false } } }, { "type": "object", "nullable": true, "properties": { "can_manage": { "description": "*Conditional*. Only relevant for `progress_source` of type `external`. This boolean indicates whether the requester has the ability to update the current value of this metric. This returns `true` if the external metric was created by the requester, `false` otherwise.", "type": "boolean", "readOnly": true, "example": true } } } ] }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "description": "The latest `status_update` posted to this goal.", "nullable": true } ] }, "status": { "type": "string", "readOnly": true, "description": "The current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect \"On Track\", \"At Risk\", and \"Off Track\", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.\n*Note* you can only write to this property if `metric` is set.", "example": "green", "nullable": true } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.goals.createGoalMetric(goalGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalsApiInstance = new Asana.GoalsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The goal metric to create.\nlet goal_gid = \"12345\"; // String | Globally unique identifier for the goal.\nlet opts = { \n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\"\n};\ngoalsApiInstance.createGoalMetric(body, goal_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goals.createGoalMetric(goalGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoals_api_instance = asana.GoalsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The goal metric to create.\ngoal_gid = \"12345\" # str | Globally unique identifier for the goal.\nopts = {\n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a goal metric\n api_response = goals_api_instance.create_goal_metric(body, goal_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling GoalsApi->create_goal_metric: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goals.create_goal_metric(goal_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goals->createGoalMetric($goal_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goals.create_goal_metric(goal_gid: 'goal_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 12, "x-moar-complexity-skipped": false } }, "/goals/{goal_gid}/setMetricCurrentValue": { "parameters": [ { "name": "goal_gid", "in": "path", "description": "Globally unique identifier for the goal.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "goal" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Update a goal metric", "description": "Updates a goal's existing metric's `current_number_value` if one exists,\notherwise responds with a 400 status code.\n\nReturns the complete updated goal metric record.", "tags": [ "Goals" ], "operationId": "updateGoalMetric", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The updated fields for the goal metric.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "current_number_value": { "description": "*Conditional*. This number is the current value of a goal metric of type number.", "type": "number", "example": 8.12 } } } } } } } }, "responses": { "200": { "description": "Successfully updated the goal metric.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "html_notes": { "type": "string", "description": "The notes of the goal with formatting as HTML.", "example": "Start building brand awareness." }, "notes": { "type": "string", "description": "Free-form textual information associated with the goal (i.e. its description).", "example": "Start building brand awareness." }, "due_on": { "type": "string", "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "example": "2019-09-15", "nullable": true }, "start_on": { "type": "string", "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "example": "2019-09-14", "nullable": true }, "is_workspace_level": { "type": "boolean", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization. Whether the goal belongs to the `workspace` (and is listed as part of the workspace\u2019s goals) or not. If it isn\u2019t a workspace-level goal, it is a team-level goal, and is associated with the goal\u2019s team.", "example": true }, "liked": { "type": "boolean", "description": "True if the goal is liked by the authorized user, false if not.", "example": false } } }, { "type": "object", "properties": { "likes": { "description": "Array of likes for users who have liked this goal.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this goal.", "type": "integer", "readOnly": true, "example": 5 }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when the `workspace` provided is an organization." } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object" } ] }, "followers": { "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "description": "Array of users who are members of this goal." }, "time_period": { "allOf": [ { "description": "

Full object requires scope: time_periods:read

\n\nA generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_period", "x-insert-after": "gid" }, "end_on": { "type": "string", "description": "The localized end date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-14" }, "start_on": { "type": "string", "description": "The localized start date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-13" }, "period": { "type": "string", "description": "The cadence and index of the time period.", "enum": [ "FY", "H1", "H2", "Q1", "Q2", "Q3", "Q4" ], "example": "Q1" }, "display_name": { "type": "string", "description": "A string representing the cadence code and the fiscal year.", "example": "Q1 FY22" } } }, { "type": "object", "nullable": true } ] }, "metric": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "number", "enum": [ "number" ] }, "precision": { "description": "*Conditional*. Only relevant for goal metrics of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.", "type": "integer", "example": 2 }, "unit": { "description": "A supported unit of measure for the goal metric, or none.", "type": "string", "enum": [ "none", "currency", "percentage" ] }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "initial_number_value": { "description": "This number is the start value of a goal metric of type number.", "type": "number", "example": 5.2 }, "target_number_value": { "description": "This number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`.", "type": "number", "example": 10.2 }, "current_number_value": { "description": "This number is the current value of a goal metric of type number.", "type": "number", "example": 8.12 }, "current_display_value": { "description": "This string is the current value of a goal metric of type string.", "type": "string", "readOnly": true, "example": "8.12" }, "progress_source": { "description": "This field defines how the progress value of a goal metric is being calculated. A goal's progress can be provided manually by the user, calculated automatically from contributing subgoals, projects, or tasks, or managed by an integration with an external data source, such as Salesforce.", "type": "string", "enum": [ "manual", "subgoal_progress", "project_task_completion", "project_milestone_completion", "task_completion", "external" ], "example": "manual" }, "is_custom_weight": { "description": "*Conditional*. Only relevant if `metric.progress_source` is one of `subgoal_progress`, `project_task_completion`, `project_milestone_completion`, or `task_completion`. If true, we use the supporting object's custom weight to calculate the goal's progress. If false, we treat all supporting objects as equally weighted", "type": "boolean", "example": false } } }, { "type": "object", "nullable": true, "properties": { "can_manage": { "description": "*Conditional*. Only relevant for `progress_source` of type `external`. This boolean indicates whether the requester has the ability to update the current value of this metric. This returns `true` if the external metric was created by the requester, `false` otherwise.", "type": "boolean", "readOnly": true, "example": true } } } ] }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "description": "The latest `status_update` posted to this goal.", "nullable": true } ] }, "status": { "type": "string", "readOnly": true, "description": "The current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect \"On Track\", \"At Risk\", and \"Off Track\", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.\n*Note* you can only write to this property if `metric` is set.", "example": "green", "nullable": true } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.goals.updateGoalMetric(goalGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalsApiInstance = new Asana.GoalsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The updated fields for the goal metric.\nlet goal_gid = \"12345\"; // String | Globally unique identifier for the goal.\nlet opts = { \n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\"\n};\ngoalsApiInstance.updateGoalMetric(body, goal_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goals.updateGoalMetric(goalGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoals_api_instance = asana.GoalsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The updated fields for the goal metric.\ngoal_gid = \"12345\" # str | Globally unique identifier for the goal.\nopts = {\n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a goal metric\n api_response = goals_api_instance.update_goal_metric(body, goal_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling GoalsApi->update_goal_metric: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goals.update_goal_metric(goal_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goals->updateGoalMetric($goal_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goals.update_goal_metric(goal_gid: 'goal_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 3, "x-moar-complexity-skipped": false } }, "/goals/{goal_gid}/addFollowers": { "parameters": [ { "name": "goal_gid", "in": "path", "description": "Globally unique identifier for the goal.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "goal" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add a collaborator to a goal", "description": "Adds followers to a goal. Returns the goal the followers were added to.\nEach goal can be associated with zero or more followers in the system.\nRequests to add/remove followers, if successful, will return the complete updated goal record, described above.", "tags": [ "Goals" ], "operationId": "addFollowers", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The followers to be added as collaborators", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "followers": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "array", "items": { "type": "string" }, "example": [ "13579", "321654" ] } }, "required": [ "followers" ] } } } } } }, "responses": { "200": { "description": "Successfully added users as collaborators.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "html_notes": { "type": "string", "description": "The notes of the goal with formatting as HTML.", "example": "Start building brand awareness." }, "notes": { "type": "string", "description": "Free-form textual information associated with the goal (i.e. its description).", "example": "Start building brand awareness." }, "due_on": { "type": "string", "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "example": "2019-09-15", "nullable": true }, "start_on": { "type": "string", "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "example": "2019-09-14", "nullable": true }, "is_workspace_level": { "type": "boolean", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization. Whether the goal belongs to the `workspace` (and is listed as part of the workspace\u2019s goals) or not. If it isn\u2019t a workspace-level goal, it is a team-level goal, and is associated with the goal\u2019s team.", "example": true }, "liked": { "type": "boolean", "description": "True if the goal is liked by the authorized user, false if not.", "example": false } } }, { "type": "object", "properties": { "likes": { "description": "Array of likes for users who have liked this goal.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this goal.", "type": "integer", "readOnly": true, "example": 5 }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when the `workspace` provided is an organization." } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object" } ] }, "followers": { "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "description": "Array of users who are members of this goal." }, "time_period": { "allOf": [ { "description": "

Full object requires scope: time_periods:read

\n\nA generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_period", "x-insert-after": "gid" }, "end_on": { "type": "string", "description": "The localized end date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-14" }, "start_on": { "type": "string", "description": "The localized start date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-13" }, "period": { "type": "string", "description": "The cadence and index of the time period.", "enum": [ "FY", "H1", "H2", "Q1", "Q2", "Q3", "Q4" ], "example": "Q1" }, "display_name": { "type": "string", "description": "A string representing the cadence code and the fiscal year.", "example": "Q1 FY22" } } }, { "type": "object", "nullable": true } ] }, "metric": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "number", "enum": [ "number" ] }, "precision": { "description": "*Conditional*. Only relevant for goal metrics of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.", "type": "integer", "example": 2 }, "unit": { "description": "A supported unit of measure for the goal metric, or none.", "type": "string", "enum": [ "none", "currency", "percentage" ] }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "initial_number_value": { "description": "This number is the start value of a goal metric of type number.", "type": "number", "example": 5.2 }, "target_number_value": { "description": "This number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`.", "type": "number", "example": 10.2 }, "current_number_value": { "description": "This number is the current value of a goal metric of type number.", "type": "number", "example": 8.12 }, "current_display_value": { "description": "This string is the current value of a goal metric of type string.", "type": "string", "readOnly": true, "example": "8.12" }, "progress_source": { "description": "This field defines how the progress value of a goal metric is being calculated. A goal's progress can be provided manually by the user, calculated automatically from contributing subgoals, projects, or tasks, or managed by an integration with an external data source, such as Salesforce.", "type": "string", "enum": [ "manual", "subgoal_progress", "project_task_completion", "project_milestone_completion", "task_completion", "external" ], "example": "manual" }, "is_custom_weight": { "description": "*Conditional*. Only relevant if `metric.progress_source` is one of `subgoal_progress`, `project_task_completion`, `project_milestone_completion`, or `task_completion`. If true, we use the supporting object's custom weight to calculate the goal's progress. If false, we treat all supporting objects as equally weighted", "type": "boolean", "example": false } } }, { "type": "object", "nullable": true, "properties": { "can_manage": { "description": "*Conditional*. Only relevant for `progress_source` of type `external`. This boolean indicates whether the requester has the ability to update the current value of this metric. This returns `true` if the external metric was created by the requester, `false` otherwise.", "type": "boolean", "readOnly": true, "example": true } } } ] }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "description": "The latest `status_update` posted to this goal.", "nullable": true } ] }, "status": { "type": "string", "readOnly": true, "description": "The current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect \"On Track\", \"At Risk\", and \"Off Track\", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.\n*Note* you can only write to this property if `metric` is set.", "example": "green", "nullable": true } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.goals.addFollowers(goalGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalsApiInstance = new Asana.GoalsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The followers to be added as collaborators\nlet goal_gid = \"12345\"; // String | Globally unique identifier for the goal.\nlet opts = { \n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\"\n};\ngoalsApiInstance.addFollowers(body, goal_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goals.addFollowers(goalGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoals_api_instance = asana.GoalsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The followers to be added as collaborators\ngoal_gid = \"12345\" # str | Globally unique identifier for the goal.\nopts = {\n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Add a collaborator to a goal\n api_response = goals_api_instance.add_followers(body, goal_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling GoalsApi->add_followers: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goals.add_followers(goal_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goals->addFollowers($goal_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goals.add_followers(goal_gid: 'goal_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/goals/{goal_gid}/removeFollowers": { "parameters": [ { "name": "goal_gid", "in": "path", "description": "Globally unique identifier for the goal.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "goal" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Remove a collaborator from a goal", "description": "Removes followers from a goal. Returns the goal the followers were removed from.\nEach goal can be associated with zero or more followers in the system.\nRequests to add/remove followers, if successful, will return the complete updated goal record, described above.", "tags": [ "Goals" ], "operationId": "removeFollowers", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The followers to be removed as collaborators", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "followers": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "array", "items": { "type": "string" }, "example": [ "13579", "321654" ] } }, "required": [ "followers" ] } } } } } }, "responses": { "200": { "description": "Successfully removed users as collaborators.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "html_notes": { "type": "string", "description": "The notes of the goal with formatting as HTML.", "example": "Start building brand awareness." }, "notes": { "type": "string", "description": "Free-form textual information associated with the goal (i.e. its description).", "example": "Start building brand awareness." }, "due_on": { "type": "string", "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "example": "2019-09-15", "nullable": true }, "start_on": { "type": "string", "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "example": "2019-09-14", "nullable": true }, "is_workspace_level": { "type": "boolean", "description": "*Conditional*. This property is only present when the `workspace` provided is an organization. Whether the goal belongs to the `workspace` (and is listed as part of the workspace\u2019s goals) or not. If it isn\u2019t a workspace-level goal, it is a team-level goal, and is associated with the goal\u2019s team.", "example": true }, "liked": { "type": "boolean", "description": "True if the goal is liked by the authorized user, false if not.", "example": false } } }, { "type": "object", "properties": { "likes": { "description": "Array of likes for users who have liked this goal.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this goal.", "type": "integer", "readOnly": true, "example": 5 }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when the `workspace` provided is an organization." } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object" } ] }, "followers": { "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "description": "Array of users who are members of this goal." }, "time_period": { "allOf": [ { "description": "

Full object requires scope: time_periods:read

\n\nA generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_period", "x-insert-after": "gid" }, "end_on": { "type": "string", "description": "The localized end date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-14" }, "start_on": { "type": "string", "description": "The localized start date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-13" }, "period": { "type": "string", "description": "The cadence and index of the time period.", "enum": [ "FY", "H1", "H2", "Q1", "Q2", "Q3", "Q4" ], "example": "Q1" }, "display_name": { "type": "string", "description": "A string representing the cadence code and the fiscal year.", "example": "Q1 FY22" } } }, { "type": "object", "nullable": true } ] }, "metric": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "number", "enum": [ "number" ] }, "precision": { "description": "*Conditional*. Only relevant for goal metrics of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.", "type": "integer", "example": 2 }, "unit": { "description": "A supported unit of measure for the goal metric, or none.", "type": "string", "enum": [ "none", "currency", "percentage" ] }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "initial_number_value": { "description": "This number is the start value of a goal metric of type number.", "type": "number", "example": 5.2 }, "target_number_value": { "description": "This number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`.", "type": "number", "example": 10.2 }, "current_number_value": { "description": "This number is the current value of a goal metric of type number.", "type": "number", "example": 8.12 }, "current_display_value": { "description": "This string is the current value of a goal metric of type string.", "type": "string", "readOnly": true, "example": "8.12" }, "progress_source": { "description": "This field defines how the progress value of a goal metric is being calculated. A goal's progress can be provided manually by the user, calculated automatically from contributing subgoals, projects, or tasks, or managed by an integration with an external data source, such as Salesforce.", "type": "string", "enum": [ "manual", "subgoal_progress", "project_task_completion", "project_milestone_completion", "task_completion", "external" ], "example": "manual" }, "is_custom_weight": { "description": "*Conditional*. Only relevant if `metric.progress_source` is one of `subgoal_progress`, `project_task_completion`, `project_milestone_completion`, or `task_completion`. If true, we use the supporting object's custom weight to calculate the goal's progress. If false, we treat all supporting objects as equally weighted", "type": "boolean", "example": false } } }, { "type": "object", "nullable": true, "properties": { "can_manage": { "description": "*Conditional*. Only relevant for `progress_source` of type `external`. This boolean indicates whether the requester has the ability to update the current value of this metric. This returns `true` if the external metric was created by the requester, `false` otherwise.", "type": "boolean", "readOnly": true, "example": true } } } ] }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "description": "The latest `status_update` posted to this goal.", "nullable": true } ] }, "status": { "type": "string", "readOnly": true, "description": "The current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect \"On Track\", \"At Risk\", and \"Off Track\", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.\n*Note* you can only write to this property if `metric` is set.", "example": "green", "nullable": true } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.goals.removeFollowers(goalGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalsApiInstance = new Asana.GoalsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The followers to be removed as collaborators\nlet goal_gid = \"12345\"; // String | Globally unique identifier for the goal.\nlet opts = { \n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\"\n};\ngoalsApiInstance.removeFollowers(body, goal_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goals.removeFollowers(goalGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoals_api_instance = asana.GoalsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The followers to be removed as collaborators\ngoal_gid = \"12345\" # str | Globally unique identifier for the goal.\nopts = {\n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Remove a collaborator from a goal\n api_response = goals_api_instance.remove_followers(body, goal_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling GoalsApi->remove_followers: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goals.remove_followers(goal_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goals->removeFollowers($goal_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goals.remove_followers(goal_gid: 'goal_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/goals/{goal_gid}/parentGoals": { "parameters": [ { "name": "goal_gid", "in": "path", "description": "Globally unique identifier for the goal.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "goal" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get parent goals from a goal", "description": "Required scope: goals:read\n\nReturns a compact representation of all of the parent goals of a goal.", "tags": [ "Goals" ], "operationId": "getParentGoalsForGoal", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "followers", "followers.name", "html_notes", "is_workspace_level", "liked", "likes", "likes.user", "likes.user.name", "metric", "metric.can_manage", "metric.currency_code", "metric.current_display_value", "metric.current_number_value", "metric.initial_number_value", "metric.is_custom_weight", "metric.precision", "metric.progress_source", "metric.resource_subtype", "metric.target_number_value", "metric.unit", "name", "notes", "num_likes", "owner", "owner.name", "privacy_setting", "start_on", "status", "team", "team.name", "time_period", "time_period.display_name", "time_period.end_on", "time_period.period", "time_period.start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified goal's parent goals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "goals:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.goals.getParentGoalsForGoal(goalGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet goalsApiInstance = new Asana.GoalsApi();\nlet goal_gid = \"12345\"; // String | Globally unique identifier for the goal.\nlet opts = { \n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\"\n};\ngoalsApiInstance.getParentGoalsForGoal(goal_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.goals.getParentGoalsForGoal(goalGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ngoals_api_instance = asana.GoalsApi(api_client)\ngoal_gid = \"12345\" # str | Globally unique identifier for the goal.\nopts = {\n 'opt_fields': \"current_status_update,current_status_update.resource_subtype,current_status_update.title,due_on,followers,followers.name,html_notes,is_workspace_level,liked,likes,likes.user,likes.user.name,metric,metric.can_manage,metric.currency_code,metric.current_display_value,metric.current_number_value,metric.initial_number_value,metric.is_custom_weight,metric.precision,metric.progress_source,metric.resource_subtype,metric.target_number_value,metric.unit,name,notes,num_likes,owner,owner.name,start_on,status,team,team.name,time_period,time_period.display_name,time_period.end_on,time_period.period,time_period.start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get parent goals from a goal\n api_response = goals_api_instance.get_parent_goals_for_goal(goal_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling GoalsApi->get_parent_goals_for_goal: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.goals.get_parent_goals_for_goal(goal_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "goals->getParentGoalsForGoal($goal_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.goals.get_parent_goals_for_goal(goal_gid: 'goal_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/jobs/{job_gid}": { "parameters": [ { "name": "job_gid", "in": "path", "description": "Globally unique identifier for the job.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "job" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a job by id", "description": "Returns the full record for a job.", "tags": [ "Jobs" ], "operationId": "getJob", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "new_graph_export", "new_graph_export.completed_at", "new_graph_export.created_at", "new_graph_export.download_url", "new_project", "new_project.name", "new_project_template", "new_project_template.name", "new_resource_export", "new_resource_export.completed_at", "new_resource_export.created_at", "new_resource_export.download_url", "new_task", "new_task.created_by", "new_task.name", "new_task.resource_subtype", "new_task_template", "new_task_template.name", "resource_subtype", "status" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "new_graph_export", "new_graph_export.completed_at", "new_graph_export.created_at", "new_graph_export.download_url", "new_project", "new_project.name", "new_project_template", "new_project_template.name", "new_resource_export", "new_resource_export.completed_at", "new_resource_export.created_at", "new_resource_export.download_url", "new_task", "new_task.created_by", "new_task.name", "new_task.resource_subtype", "new_task_template", "new_task_template.name", "resource_subtype", "status" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved Job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A *job* is an object representing a process that handles asynchronous work.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "job", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "duplicate_task" }, "status": { "description": "The current status of this job.", "type": "string", "enum": [ "not_started", "in_progress", "succeeded", "failed" ], "readOnly": true, "example": "in_progress" }, "new_project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "new_task": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "nullable": true } ] }, "new_project_template": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, "new_graph_export": { "description": "A *graph_export* object represents a request to export the data starting from a parent object", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "graph_export", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin JSON format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or\nfailed. If present, this URL may only be valid for 1 hour from\nthe time of retrieval. You should avoid persisting this URL\nsomewhere and rather refresh on demand to ensure you do not keep\nstale URLs.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/domain_export/7588024658887731/download/ domain_export_2563645399633793_7588024658887731_2023018-201726.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Content-Sha256=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host&x-id=GetObject#_=_" }, "completed_at": { "description": "The time at which this resource was completed.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } }, "new_resource_export": { "description": "A *resource_export* object represents a request to bulk export objects for one or more resources.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "export_request", "x-insert-after": "gid" }, "created_at": { "description": "The time at which the resource export object was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin [JSON Lines](https://jsonlines.org/) format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or failed.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/object_export/7588024658887731/download/ object_export_2563645399633793_7588024658887731_2023018-201726.jsonl.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Credential=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host" }, "completed_at": { "description": "The time at which this resource was completed. This will be null if the export is still in progress.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJob result = client.jobs.getJob(jobGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet jobsApiInstance = new Asana.JobsApi();\nlet job_gid = \"12345\"; // String | Globally unique identifier for the job.\nlet opts = { \n 'opt_fields': \"new_graph_export,new_graph_export.completed_at,new_graph_export.created_at,new_graph_export.download_url,new_project,new_project.name,new_project_template,new_project_template.name,new_resource_export,new_resource_export.completed_at,new_resource_export.created_at,new_resource_export.download_url,new_task,new_task.created_by,new_task.name,new_task.resource_subtype,resource_subtype,status\"\n};\njobsApiInstance.getJob(job_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.jobs.getJob(jobGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\njobs_api_instance = asana.JobsApi(api_client)\njob_gid = \"12345\" # str | Globally unique identifier for the job.\nopts = {\n 'opt_fields': \"new_graph_export,new_graph_export.completed_at,new_graph_export.created_at,new_graph_export.download_url,new_project,new_project.name,new_project_template,new_project_template.name,new_resource_export,new_resource_export.completed_at,new_resource_export.created_at,new_resource_export.download_url,new_task,new_task.created_by,new_task.name,new_task.resource_subtype,resource_subtype,status\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a job by id\n api_response = jobs_api_instance.get_job(job_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling JobsApi->get_job: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.jobs.get_job(job_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "jobs->getJob($job_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.jobs.get_job(job_gid: 'job_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/memberships": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get multiple memberships", "description": "Returns compact `goal_membership`, `project_membership`, `portfolio_membership`, or `custom_field_membership` records. The possible types for `parent` in this request are `goal`, `project`, `portfolio`, or `custom_field`. An additional member (user GID or team GID) can be passed in to filter to a specific membership.", "tags": [ "Memberships" ], "operationId": "getMemberships", "parameters": [ { "name": "parent", "in": "query", "description": "Globally unique identifier for `goal`, `project`, `portfolio`, or `custom_field`.", "schema": { "type": "string" }, "example": "159874" }, { "name": "member", "in": "query", "description": "Globally unique identifier for `team` or `user`.", "schema": { "type": "string" }, "example": "1061493" }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "offset", "path", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "offset", "path", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested membership.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "anyOf": [ { "allOf": [ { "description": "This object represents a user's connection to a goal.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "membership" }, "resource_subtype": { "type": "string", "readOnly": true, "description": "The type of membership.", "example": "goal_membership" }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "parent": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } }, { "type": "object", "readOnly": true } ] }, "role": { "type": "string", "description": "*Deprecated: Describes if the member is a commenter or editor in goal.*", "enum": [ "commenter", "editor" ], "deprecated": true, "example": "editor" }, "access_level": { "type": "string", "description": "\"Describes the membership access level for the goal. (`admin` and `viewer` are currently only available when you include the header: `Asana-Enable: goal_sals_api`.) This is preferred over role.\"", "enum": [ "viewer", "commenter", "editor", "admin" ], "example": "editor" }, "goal": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } }, { "type": "object", "readOnly": true, "deprecated": true, "description": "*Deprecated: new integrations should prefer the `parent` field.* A *Goal* is an object in the goal-tracking system that helps your organization drive measurable results." } ] } } }, { "type": "object", "properties": { "is_commenter": { "type": "boolean", "deprecated": true, "readOnly": true, "description": "*Deprecated: new integrations should prefer the `role` field.* Describes if the member is comment only in goal. Will be null if the `goal_sals_api` change flag is enabled.", "example": false }, "is_editor": { "type": "boolean", "deprecated": true, "readOnly": true, "description": "*Deprecated: new integrations should prefer the `role` field.* Describes if the member is editor in goal. Will be null if the `goal_sals_api` change flag is enabled.", "example": false } } } ] }, { "allOf": [ { "description": "This object describes a team or a user's membership to a project including their level of access (Admin, Editor, Commenter, or Viewer).", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_membership", "x-insert-after": "gid" }, "parent": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, commenter, or viewer access to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "readOnly": true, "example": "admin" } } }, { "type": "object", "properties": { "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "membership" }, "resource_subtype": { "description": "Type of the membership.", "type": "string", "example": "project_membership" } } } ] }, { "allOf": [ { "description": "This object determines if a user is a member of a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio_membership", "x-insert-after": "gid" }, "parent": { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, or viewer access to the portfolio. Portfolios do not support commenter access yet.", "type": "string", "enum": [ "admin", "editor", "viewer" ], "readOnly": true, "example": "admin" } } }, { "type": "object", "properties": { "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "membership" }, "resource_subtype": { "description": "Type of the membership.", "type": "string", "example": "portfolio_membership" } } } ] }, { "description": "This object describes a user or team's membership to a custom field including their level of access (Admin, Editor, or User).", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_membership", "x-insert-after": "gid" }, "resource_subtype": { "description": "Type of the membership.", "type": "string", "example": "custom_field_membership" }, "parent": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, or user access to the custom field.", "type": "string", "enum": [ "admin", "editor", "user" ], "readOnly": true, "example": "admin" } } } ] } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet membershipsApiInstance = new Asana.MembershipsApi();\nlet opts = { \n 'parent': \"159874\", \n 'member': \"1061493\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"offset,path,uri\"\n};\nmembershipsApiInstance.getMemberships(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.memberships.getMemberships({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nmemberships_api_instance = asana.MembershipsApi(api_client)\nopts = {\n 'parent': \"159874\", # str | Globally unique identifier for `goal`, `project`, `portfolio`, or `custom_field`.\n 'member': \"1061493\", # str | Globally unique identifier for `team` or `user`.\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"offset,path,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple memberships\n api_response = memberships_api_instance.get_memberships(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling MembershipsApi->get_memberships: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.memberships.get_memberships({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "memberships->getMemberships(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.memberships.get_memberships(parent: ''parent_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a membership", "description": "Creates a new membership in a `goal`, `project`, `portfolio`, or `custom_field`, where members can be Teams or Users.\n\nReturns the full record of the newly created membership.", "tags": [ "Memberships" ], "operationId": "createMembership", "requestBody": { "description": "The updated fields for the membership.", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "access_level": { "description": "Sets the access level for the member. Goals can have access levels `viewer`, `commenter`, `editor` or `admin` (`viewer` and `admin` are currently only available for Goals when you include the `Asana-Enable: goal_sals_api` change flag header). Projects can have access levels `admin`, `editor` or `commenter`. Portfolios can have access levels `admin`, `editor` or `viewer`. Custom Fields can have access levels `admin`, `editor` or `user`.", "type": "string", "example": "editor" } } }, { "type": "object", "properties": { "member": { "description": "The gid of the user or team.", "type": "string", "example": 12345 }, "parent": { "description": "The gid of the `goal`, `project`, or `portfolio` to add the member to.", "type": "string", "example": "987654" }, "role": { "description": "*Deprecated: new integrations should use access_level* The role given to the member. Optional argument, will default to `commenter` for goals and the default project role for projects. Can be `editor` or `commenter` for goals. Can be `admin`,`editor` or `commenter` for projects.", "type": "string", "deprecated": true, "example": "editor" } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created the requested membership.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "allOf": [ { "description": "This object represents a user's connection to a goal.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "membership" }, "resource_subtype": { "type": "string", "readOnly": true, "description": "The type of membership.", "example": "goal_membership" }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "parent": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } }, { "type": "object", "readOnly": true } ] }, "role": { "type": "string", "description": "*Deprecated: Describes if the member is a commenter or editor in goal.*", "enum": [ "commenter", "editor" ], "deprecated": true, "example": "editor" }, "access_level": { "type": "string", "description": "\"Describes the membership access level for the goal. (`admin` and `viewer` are currently only available when you include the header: `Asana-Enable: goal_sals_api`.) This is preferred over role.\"", "enum": [ "viewer", "commenter", "editor", "admin" ], "example": "editor" }, "goal": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } }, { "type": "object", "readOnly": true, "deprecated": true, "description": "*Deprecated: new integrations should prefer the `parent` field.* A *Goal* is an object in the goal-tracking system that helps your organization drive measurable results." } ] } } }, { "type": "object", "properties": { "user": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "deprecated": true, "readOnly": true, "description": "*Deprecated: new integrations should prefer the `member` field.* A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks." } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "deprecated": true, "readOnly": true, "description": "*Deprecated:* A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace." } ] } } } ] }, { "allOf": [ { "description": "This object describes a team or a user's membership to a project including their level of access (Admin, Editor, Commenter, or Viewer).", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_membership", "x-insert-after": "gid" }, "parent": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, commenter, or viewer access to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "readOnly": true, "example": "admin" } } }, { "type": "object", "properties": { "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "membership" }, "resource_subtype": { "description": "Type of the membership.", "type": "string", "example": "project_membership" } } } ] }, { "description": "This object determines if a user is a member of a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio_membership", "x-insert-after": "gid" }, "parent": { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, or viewer access to the portfolio. Portfolios do not support commenter access yet.", "type": "string", "enum": [ "admin", "editor", "viewer" ], "readOnly": true, "example": "admin" } } }, { "description": "This object describes a user or team's membership to a custom field including their level of access (Admin, Editor, or User).", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_membership", "x-insert-after": "gid" }, "resource_subtype": { "description": "Type of the membership.", "type": "string", "example": "custom_field_membership" }, "parent": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, or user access to the custom field.", "type": "string", "enum": [ "admin", "editor", "user" ], "readOnly": true, "example": "admin" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet membershipsApiInstance = new Asana.MembershipsApi();\nlet opts = { \n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}\n};\nmembershipsApiInstance.createMembership(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.memberships.createMembership({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nmemberships_api_instance = asana.MembershipsApi(api_client)\nopts = {\n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, # dict | The updated fields for the membership.\n}\n\ntry:\n # Create a membership\n api_response = memberships_api_instance.create_membership(opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling MembershipsApi->create_membership: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.memberships.create_membership({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "memberships->createMembership(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.memberships.create_membership(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 4, "x-moar-complexity-skipped": false } }, "/memberships/{membership_gid}": { "parameters": [ { "name": "membership_gid", "in": "path", "description": "Globally unique identifier for the membership.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "membership" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a membership", "description": "Returns a `project_membership`, `goal_membership`, `portfolio_membership`, or `custom_field_membership` record for a membership id.", "tags": [ "Memberships" ], "operationId": "getMembership", "responses": { "200": { "description": "Successfully retrieved the record for a single membership.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "allOf": [ { "description": "This object represents a user's connection to a goal.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "membership" }, "resource_subtype": { "type": "string", "readOnly": true, "description": "The type of membership.", "example": "goal_membership" }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "parent": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } }, { "type": "object", "readOnly": true } ] }, "role": { "type": "string", "description": "*Deprecated: Describes if the member is a commenter or editor in goal.*", "enum": [ "commenter", "editor" ], "deprecated": true, "example": "editor" }, "access_level": { "type": "string", "description": "\"Describes the membership access level for the goal. (`admin` and `viewer` are currently only available when you include the header: `Asana-Enable: goal_sals_api`.) This is preferred over role.\"", "enum": [ "viewer", "commenter", "editor", "admin" ], "example": "editor" }, "goal": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } }, { "type": "object", "readOnly": true, "deprecated": true, "description": "*Deprecated: new integrations should prefer the `parent` field.* A *Goal* is an object in the goal-tracking system that helps your organization drive measurable results." } ] } } }, { "type": "object", "properties": { "user": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "deprecated": true, "readOnly": true, "description": "*Deprecated: new integrations should prefer the `member` field.* A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks." } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "deprecated": true, "readOnly": true, "description": "*Deprecated:* A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace." } ] } } } ] }, { "allOf": [ { "description": "This object describes a team or a user's membership to a project including their level of access (Admin, Editor, Commenter, or Viewer).", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_membership", "x-insert-after": "gid" }, "parent": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, commenter, or viewer access to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "readOnly": true, "example": "admin" } } }, { "type": "object", "properties": { "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "membership" }, "resource_subtype": { "description": "Type of the membership.", "type": "string", "example": "project_membership" } } } ] }, { "description": "This object determines if a user is a member of a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio_membership", "x-insert-after": "gid" }, "parent": { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, or viewer access to the portfolio. Portfolios do not support commenter access yet.", "type": "string", "enum": [ "admin", "editor", "viewer" ], "readOnly": true, "example": "admin" } } }, { "description": "This object describes a user or team's membership to a custom field including their level of access (Admin, Editor, or User).", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_membership", "x-insert-after": "gid" }, "resource_subtype": { "description": "Type of the membership.", "type": "string", "example": "custom_field_membership" }, "parent": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, or user access to the custom field.", "type": "string", "enum": [ "admin", "editor", "user" ], "readOnly": true, "example": "admin" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet membershipsApiInstance = new Asana.MembershipsApi();\nlet membership_gid = \"12345\"; // String | Globally unique identifier for the membership.\n\nmembershipsApiInstance.getMembership(membership_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.memberships.getMembership(membershipGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nmemberships_api_instance = asana.MembershipsApi(api_client)\nmembership_gid = \"12345\" # str | Globally unique identifier for the membership.\n\n\ntry:\n # Get a membership\n api_response = memberships_api_instance.get_membership(membership_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling MembershipsApi->get_membership: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.memberships.get_membership(membership_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a membership", "description": "An existing membership can be updated by making a `PUT` request on the membership. Only the fields provided in the `data` block will be updated;\nany unspecified fields will remain unchanged. Memberships on `goals`, `projects`, `portfolios`, and `custom_fields` can be updated.\n\nReturns the full record of the updated membership.", "tags": [ "Memberships" ], "operationId": "updateMembership", "requestBody": { "description": "The membership to update.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "access_level": { "description": "Sets the access level for the member. Goals can have access levels `viewer`, `commenter`, `editor` or `admin` (`viewer` and `admin` are currently only available for Goals when you include the `Asana-Enable: goal_sals_api` change flag header). Projects can have access levels `admin`, `editor` or `commenter`. Portfolios can have access levels `admin`, `editor` or `viewer`. Custom Fields can have access levels `admin`, `editor` or `user`.", "type": "string", "example": "editor" } } } } } } } }, "responses": { "200": { "description": "Successfully updated the requested membership.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "allOf": [ { "description": "This object represents a user's connection to a goal.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "membership" }, "resource_subtype": { "type": "string", "readOnly": true, "description": "The type of membership.", "example": "goal_membership" }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "parent": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } }, { "type": "object", "readOnly": true } ] }, "role": { "type": "string", "description": "*Deprecated: Describes if the member is a commenter or editor in goal.*", "enum": [ "commenter", "editor" ], "deprecated": true, "example": "editor" }, "access_level": { "type": "string", "description": "\"Describes the membership access level for the goal. (`admin` and `viewer` are currently only available when you include the header: `Asana-Enable: goal_sals_api`.) This is preferred over role.\"", "enum": [ "viewer", "commenter", "editor", "admin" ], "example": "editor" }, "goal": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "goal", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the goal.", "example": "Grow web traffic by 30%" }, "owner": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] } } }, { "type": "object", "readOnly": true, "deprecated": true, "description": "*Deprecated: new integrations should prefer the `parent` field.* A *Goal* is an object in the goal-tracking system that helps your organization drive measurable results." } ] } } }, { "type": "object", "properties": { "user": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "deprecated": true, "readOnly": true, "description": "*Deprecated: new integrations should prefer the `member` field.* A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks." } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "deprecated": true, "readOnly": true, "description": "*Deprecated:* A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace." } ] } } } ] }, { "allOf": [ { "description": "This object describes a team or a user's membership to a project including their level of access (Admin, Editor, Commenter, or Viewer).", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_membership", "x-insert-after": "gid" }, "parent": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, commenter, or viewer access to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "readOnly": true, "example": "admin" } } }, { "type": "object", "properties": { "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "membership" }, "resource_subtype": { "description": "Type of the membership.", "type": "string", "example": "project_membership" } } } ] }, { "description": "This object determines if a user is a member of a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio_membership", "x-insert-after": "gid" }, "parent": { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, or viewer access to the portfolio. Portfolios do not support commenter access yet.", "type": "string", "enum": [ "admin", "editor", "viewer" ], "readOnly": true, "example": "admin" } } }, { "description": "This object describes a user or team's membership to a custom field including their level of access (Admin, Editor, or User).", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_membership", "x-insert-after": "gid" }, "resource_subtype": { "description": "Type of the membership.", "type": "string", "example": "custom_field_membership" }, "parent": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, or user access to the custom field.", "type": "string", "enum": [ "admin", "editor", "user" ], "readOnly": true, "example": "admin" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet membershipsApiInstance = new Asana.MembershipsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The membership to update.\nlet membership_gid = \"12345\"; // String | Globally unique identifier for the membership.\n\nmembershipsApiInstance.updateMembership(body, membership_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.memberships.updateMembership(membershipGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nmemberships_api_instance = asana.MembershipsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The membership to update.\nmembership_gid = \"12345\" # str | Globally unique identifier for the membership.\n\n\ntry:\n # Update a membership\n api_response = memberships_api_instance.update_membership(body, membership_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling MembershipsApi->update_membership: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.memberships.update_membership(membership_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "memberships->updateMembership($membership_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.memberships.update_membership(membership_gid: 'membership_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a membership", "description": "A specific, existing membership for a `goal`, `project`, `portfolio` or `custom_field` can be deleted by making a `DELETE` request\non the URL for that membership.\n\nReturns an empty data record.", "tags": [ "Memberships" ], "operationId": "deleteMembership", "responses": { "200": { "description": "Successfully deleted the requested membership.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet membershipsApiInstance = new Asana.MembershipsApi();\nlet membership_gid = \"12345\"; // String | Globally unique identifier for the membership.\n\nmembershipsApiInstance.deleteMembership(membership_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.memberships.deleteMembership(membershipGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nmemberships_api_instance = asana.MembershipsApi(api_client)\nmembership_gid = \"12345\" # str | Globally unique identifier for the membership.\n\n\ntry:\n # Delete a membership\n api_response = memberships_api_instance.delete_membership(membership_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling MembershipsApi->delete_membership: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.memberships.delete_membership(membership_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "memberships->deleteMembership($membership_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.memberships.delete_membership(membership_gid: 'membership_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/organization_exports": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Create an organization export request", "description": "This method creates a request to export an Organization. Asana will complete the export at some point after you create the request.", "tags": [ "Organization exports" ], "operationId": "createOrganizationExport", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "created_at", "download_url", "organization", "organization.name", "state" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "download_url", "organization", "organization.name", "state" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The organization to export.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An *organization_export* request starts a job to export the complete data of the given Organization.", "properties": { "organization": { "description": "Globally unique identifier for the workspace or organization.", "type": "string", "example": "1331" } } } } } } } }, "responses": { "201": { "description": "Successfully created organization export request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "An *organization_export* object represents a request to export the complete data of an Organization in JSON format.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "organization_export", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export of the organization\nin JSON format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or\nfailed. If present, this URL may only be valid for 1 hour from\nthe time of retrieval. You should avoid persisting this URL\nsomewhere and rather refresh on demand to ensure you do not keep\nstale URLs.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/domain_export/7588024658887731/download/ domain_export_2563645399633793_7588024658887731_2023018-201726.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Content-Sha256=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host&x-id=GetObject#_=_" }, "state": { "description": "The current state of the export.", "type": "string", "enum": [ "pending", "started", "finished", "error" ], "readOnly": true, "example": "started" }, "organization": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nOrganizationExport result = client.organizationexports.createOrganizationExport()\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet organizationExportsApiInstance = new Asana.OrganizationExportsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The organization to export.\nlet opts = { \n 'opt_fields': \"created_at,download_url,organization,organization.name,state\"\n};\norganizationExportsApiInstance.createOrganizationExport(body, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.organizationexports.createOrganizationExport({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\norganization_exports_api_instance = asana.OrganizationExportsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The organization to export.\nopts = {\n 'opt_fields': \"created_at,download_url,organization,organization.name,state\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create an organization export request\n api_response = organization_exports_api_instance.create_organization_export(body, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling OrganizationExportsApi->create_organization_export: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.organization_exports.create_organization_export({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "organizationexports->createOrganizationExport(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.organization_exports.create_organization_export(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/organization_exports/{organization_export_gid}": { "parameters": [ { "name": "organization_export_gid", "in": "path", "description": "Globally unique identifier for the organization export.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "organization_export" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get details on an org export request", "description": "Returns details of a previously-requested Organization export.", "tags": [ "Organization exports" ], "operationId": "getOrganizationExport", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "created_at", "download_url", "organization", "organization.name", "state" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "download_url", "organization", "organization.name", "state" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved organization export object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "An *organization_export* object represents a request to export the complete data of an Organization in JSON format.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "organization_export", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export of the organization\nin JSON format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or\nfailed. If present, this URL may only be valid for 1 hour from\nthe time of retrieval. You should avoid persisting this URL\nsomewhere and rather refresh on demand to ensure you do not keep\nstale URLs.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/domain_export/7588024658887731/download/ domain_export_2563645399633793_7588024658887731_2023018-201726.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Content-Sha256=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host&x-id=GetObject#_=_" }, "state": { "description": "The current state of the export.", "type": "string", "enum": [ "pending", "started", "finished", "error" ], "readOnly": true, "example": "started" }, "organization": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nOrganizationExport result = client.organizationexports.getOrganizationExport(organizationExportGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet organizationExportsApiInstance = new Asana.OrganizationExportsApi();\nlet organization_export_gid = \"12345\"; // String | Globally unique identifier for the organization export.\nlet opts = { \n 'opt_fields': \"created_at,download_url,organization,organization.name,state\"\n};\norganizationExportsApiInstance.getOrganizationExport(organization_export_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.organizationexports.getOrganizationExport(organizationExportGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\norganization_exports_api_instance = asana.OrganizationExportsApi(api_client)\norganization_export_gid = \"12345\" # str | Globally unique identifier for the organization export.\nopts = {\n 'opt_fields': \"created_at,download_url,organization,organization.name,state\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get details on an org export request\n api_response = organization_exports_api_instance.get_organization_export(organization_export_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling OrganizationExportsApi->get_organization_export: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.organization_exports.get_organization_export(organization_export_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "organizationexports->getOrganizationExport($organization_export_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.organization_exports.get_organization_export(organization_export_gid: 'organization_export_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/portfolio_memberships": { "parameters": [ { "name": "portfolio", "in": "query", "description": "The portfolio to filter results on.", "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, { "name": "workspace", "in": "query", "description": "The workspace to filter results on.", "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "user", "in": "query", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get multiple portfolio memberships", "description": "Returns a list of portfolio memberships in compact representation. You must specify `portfolio`, `portfolio` and `user`, or `workspace` and `user`.", "tags": [ "Portfolio memberships" ], "operationId": "getPortfolioMemberships", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "access_level", "offset", "path", "portfolio", "portfolio.name", "uri", "user", "user.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "access_level", "offset", "path", "portfolio", "portfolio.name", "uri", "user", "user.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved portfolio memberships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "This object determines if a user is a member of a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio_membership", "x-insert-after": "gid" }, "portfolio": { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, or viewer access to the portfolio. Portfolios do not support commenter access yet.", "type": "string", "enum": [ "admin", "editor", "viewer" ], "readOnly": true, "example": "admin" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.portfoliomemberships.getPortfolioMemberships(user, workspace, portfolio)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfolioMembershipsApiInstance = new Asana.PortfolioMembershipsApi();\nlet opts = { \n 'portfolio': \"12345\", \n 'workspace': \"12345\", \n 'user': \"me\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"access_level,offset,path,portfolio,portfolio.name,uri,user,user.name\"\n};\nportfolioMembershipsApiInstance.getPortfolioMemberships(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfoliomemberships.getPortfolioMemberships({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolio_memberships_api_instance = asana.PortfolioMembershipsApi(api_client)\nopts = {\n 'portfolio': \"12345\", # str | The portfolio to filter results on.\n 'workspace': \"12345\", # str | The workspace to filter results on.\n 'user': \"me\", # str | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"access_level,offset,path,portfolio,portfolio.name,uri,user,user.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple portfolio memberships\n api_response = portfolio_memberships_api_instance.get_portfolio_memberships(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling PortfolioMembershipsApi->get_portfolio_memberships: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolio_memberships.get_portfolio_memberships({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfoliomemberships->getPortfolioMemberships(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolio_memberships.get_portfolio_memberships(param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/portfolio_memberships/{portfolio_membership_gid}": { "parameters": [ { "name": "portfolio_membership_gid", "in": "path", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "portfolio_membership" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a portfolio membership", "description": "Returns the complete portfolio record for a single portfolio membership.", "tags": [ "Portfolio memberships" ], "operationId": "getPortfolioMembership", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "access_level", "portfolio", "portfolio.name", "user", "user.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "access_level", "portfolio", "portfolio.name", "user", "user.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested portfolio membership.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "This object determines if a user is a member of a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio_membership", "x-insert-after": "gid" }, "portfolio": { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, or viewer access to the portfolio. Portfolios do not support commenter access yet.", "type": "string", "enum": [ "admin", "editor", "viewer" ], "readOnly": true, "example": "admin" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nPortfolioMembership result = client.portfoliomemberships.getPortfolioMembership(portfolioMembershipGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfolioMembershipsApiInstance = new Asana.PortfolioMembershipsApi();\nlet portfolio_membership_gid = \"1331\"; // String | \nlet opts = { \n 'opt_fields': \"access_level,portfolio,portfolio.name,user,user.name\"\n};\nportfolioMembershipsApiInstance.getPortfolioMembership(portfolio_membership_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfoliomemberships.getPortfolioMembership(portfolioMembershipGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolio_memberships_api_instance = asana.PortfolioMembershipsApi(api_client)\nportfolio_membership_gid = \"1331\" # str | \nopts = {\n 'opt_fields': \"access_level,portfolio,portfolio.name,user,user.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a portfolio membership\n api_response = portfolio_memberships_api_instance.get_portfolio_membership(portfolio_membership_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling PortfolioMembershipsApi->get_portfolio_membership: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolio_memberships.get_portfolio_membership(portfolio_membership_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfoliomemberships->getPortfolioMembership($portfolio_membership_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolio_memberships.get_portfolio_membership(portfolio_membership_gid: 'portfolio_membership_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/portfolios/{portfolio_gid}/portfolio_memberships": { "parameters": [ { "name": "portfolio_gid", "in": "path", "description": "Globally unique identifier for the portfolio.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, { "name": "user", "in": "query", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get memberships from a portfolio", "description": "Returns the compact portfolio membership records for the portfolio.", "tags": [ "Portfolio memberships" ], "operationId": "getPortfolioMembershipsForPortfolio", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "access_level", "offset", "path", "portfolio", "portfolio.name", "uri", "user", "user.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "access_level", "offset", "path", "portfolio", "portfolio.name", "uri", "user", "user.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested portfolio's memberships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "This object determines if a user is a member of a portfolio.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio_membership", "x-insert-after": "gid" }, "portfolio": { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, or viewer access to the portfolio. Portfolios do not support commenter access yet.", "type": "string", "enum": [ "admin", "editor", "viewer" ], "readOnly": true, "example": "admin" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.portfoliomemberships.getPortfolioMembershipsForPortfolio(portfolioGid, user)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfolioMembershipsApiInstance = new Asana.PortfolioMembershipsApi();\nlet portfolio_gid = \"12345\"; // String | Globally unique identifier for the portfolio.\nlet opts = { \n 'user': \"me\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"access_level,offset,path,portfolio,portfolio.name,uri,user,user.name\"\n};\nportfolioMembershipsApiInstance.getPortfolioMembershipsForPortfolio(portfolio_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfoliomemberships.getPortfolioMembershipsForPortfolio(portfolioGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolio_memberships_api_instance = asana.PortfolioMembershipsApi(api_client)\nportfolio_gid = \"12345\" # str | Globally unique identifier for the portfolio.\nopts = {\n 'user': \"me\", # str | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"access_level,offset,path,portfolio,portfolio.name,uri,user,user.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get memberships from a portfolio\n api_response = portfolio_memberships_api_instance.get_portfolio_memberships_for_portfolio(portfolio_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling PortfolioMembershipsApi->get_portfolio_memberships_for_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolio_memberships.get_portfolio_memberships_for_portfolio(portfolio_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfoliomemberships->getPortfolioMembershipsForPortfolio($portfolio_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolio_memberships.get_portfolio_memberships_for_portfolio(portfolio_gid: 'portfolio_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/portfolios": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get multiple portfolios", "description": "Required scope: portfolios:read\n\nReturns a list of the portfolios in compact representation that are owned by the current API user.", "tags": [ "Portfolios" ], "operationId": "getPortfolios", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "workspace", "in": "query", "required": true, "description": "The workspace or organization to filter portfolios on.", "schema": { "type": "string" }, "example": "1331" }, { "name": "owner", "in": "query", "required": false, "description": "The user who owns the portfolio. Currently, API users can only get a list of portfolios that they themselves own, unless the request is made from a Service Account. In the case of a Service Account, if this parameter is specified, then all portfolios owned by this parameter are returned. Otherwise, all portfolios across the workspace are returned.", "schema": { "type": "string" }, "example": "14916" }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "created_at", "created_by", "created_by.name", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "members", "members.name", "name", "offset", "owner", "owner.name", "path", "permalink_url", "privacy_setting", "project_templates", "project_templates.name", "public", "start_on", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "created_at", "created_by", "created_by.name", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "members", "members.name", "name", "offset", "owner", "owner.name", "path", "permalink_url", "privacy_setting", "project_templates", "project_templates.name", "public", "start_on", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved portfolios.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "portfolios:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.portfolios.getPortfolios(owner, workspace)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfoliosApiInstance = new Asana.PortfoliosApi();\nlet workspace = \"1331\"; // String | The workspace or organization to filter portfolios on.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'owner': \"14916\", \n 'opt_fields': \"archived,color,created_at,created_by,created_by.name,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,due_on,members,members.name,name,offset,owner,owner.name,path,permalink_url,privacy_setting,project_templates,project_templates.name,public,start_on,uri,workspace,workspace.name\"\n};\nportfoliosApiInstance.getPortfolios(workspace, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfolios.getPortfolios({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolios_api_instance = asana.PortfoliosApi(api_client)\nworkspace = \"1331\" # str | The workspace or organization to filter portfolios on.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'owner': \"14916\", # str | The user who owns the portfolio. Currently, API users can only get a list of portfolios that they themselves own, unless the request is made from a Service Account. In the case of a Service Account, if this parameter is specified, then all portfolios owned by this parameter are returned. Otherwise, all portfolios across the workspace are returned.\n 'opt_fields': \"archived,color,created_at,created_by,created_by.name,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,due_on,members,members.name,name,offset,owner,owner.name,path,permalink_url,privacy_setting,project_templates,project_templates.name,public,start_on,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple portfolios\n api_response = portfolios_api_instance.get_portfolios(workspace, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling PortfoliosApi->get_portfolios: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolios.get_portfolios({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfolios->getPortfolios(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolios.get_portfolios(workspace: ''workspace_example'', owner: ''owner_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a portfolio", "description": "Required scope: portfolios:write\n\nCreates a new portfolio in the given workspace with the supplied name.\n\nNote that portfolios created in the Asana UI may have some state\n(like the \u201cPriority\u201d custom field) which is automatically added\nto the portfolio when it is created. Portfolios created via our\nAPI will *not* be created with the same initial state to allow\nintegrations to create their own starting state on a portfolio.", "tags": [ "Portfolios" ], "operationId": "createPortfolio", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "created_at", "created_by", "created_by.name", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "members", "members.name", "name", "owner", "owner.name", "permalink_url", "privacy_setting", "project_templates", "project_templates.name", "public", "start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "created_at", "created_by", "created_by.name", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "members", "members.name", "name", "owner", "owner.name", "permalink_url", "privacy_setting", "project_templates", "project_templates.name", "public", "start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The portfolio to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, { "type": "object", "properties": { "archived": { "description": "[Opt In](/docs/inputoutput-options). True if the portfolio is archived, false if not. Archived portfolios do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the portfolio.", "type": "string", "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray" ], "example": "light-green" }, "start_on": { "description": "The day on which work for this portfolio begins, or null if the portfolio has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "due_on": { "description": "The day on which this portfolio is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "default_access_level": { "description": "The default access level when inviting new members to the portfolio", "type": "string", "enum": [ "admin", "editor", "viewer" ], "example": "viewer" } } } ] }, { "type": "object", "properties": { "workspace": { "type": "string", "description": "*Create-only*. The workspace or organization that the portfolio belongs to.", "example": "167589" }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created portfolio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, { "type": "object", "properties": { "archived": { "description": "[Opt In](/docs/inputoutput-options). True if the portfolio is archived, false if not. Archived portfolios do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the portfolio.", "type": "string", "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray" ], "example": "light-green" }, "start_on": { "description": "The day on which work for this portfolio begins, or null if the portfolio has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "due_on": { "description": "The day on which this portfolio is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "default_access_level": { "description": "The default access level when inviting new members to the portfolio", "type": "string", "enum": [ "admin", "editor", "viewer" ], "example": "viewer" } } } ] }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of custom field settings applied to the portfolio.", "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "description": "The latest `status_update` posted to this portfolio.", "nullable": true } ] }, "custom_fields": { "description": "Array of Custom Fields.", "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "members": { "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "owner": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "description": "*Create-only*. The workspace or organization that the portfolio belongs to." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" }, "public": { "description": "True if the portfolio is public to its workspace members.", "type": "boolean", "example": false }, "privacy_setting": { "description": "The privacy setting of the portfolio. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_domain", "members_only" ], "example": "members_only" }, "project_templates": { "description": "Array of project templates that are in the portfolio", "type": "array", "readOnly": true, "items": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "portfolios:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nPortfolio result = client.portfolios.createPortfolio()\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfoliosApiInstance = new Asana.PortfoliosApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The portfolio to create.\nlet opts = { \n 'opt_fields': \"archived,color,created_at,created_by,created_by.name,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,due_on,members,members.name,name,owner,owner.name,permalink_url,privacy_setting,project_templates,project_templates.name,public,start_on,workspace,workspace.name\"\n};\nportfoliosApiInstance.createPortfolio(body, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfolios.createPortfolio({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolios_api_instance = asana.PortfoliosApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The portfolio to create.\nopts = {\n 'opt_fields': \"archived,color,created_at,created_by,created_by.name,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,due_on,members,members.name,name,owner,owner.name,permalink_url,privacy_setting,project_templates,project_templates.name,public,start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a portfolio\n api_response = portfolios_api_instance.create_portfolio(body, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling PortfoliosApi->create_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolios.create_portfolio({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfolios->createPortfolio(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolios.create_portfolio(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 10, "x-moar-complexity-skipped": false } }, "/portfolios/{portfolio_gid}": { "parameters": [ { "name": "portfolio_gid", "in": "path", "description": "Globally unique identifier for the portfolio.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a portfolio", "description": "Required scope: portfolios:read\n\n\n \n \n \n \n \n \n \n \n
FieldRequired Scope
custom_field_settingscustom_fields:read
\n\nReturns the complete portfolio record for a single portfolio.", "tags": [ "Portfolios" ], "operationId": "getPortfolio", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "created_at", "created_by", "created_by.name", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "members", "members.name", "name", "owner", "owner.name", "permalink_url", "privacy_setting", "project_templates", "project_templates.name", "public", "start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "created_at", "created_by", "created_by.name", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "members", "members.name", "name", "owner", "owner.name", "permalink_url", "privacy_setting", "project_templates", "project_templates.name", "public", "start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested portfolio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, { "type": "object", "properties": { "archived": { "description": "[Opt In](/docs/inputoutput-options). True if the portfolio is archived, false if not. Archived portfolios do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the portfolio.", "type": "string", "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray" ], "example": "light-green" }, "start_on": { "description": "The day on which work for this portfolio begins, or null if the portfolio has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "due_on": { "description": "The day on which this portfolio is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "default_access_level": { "description": "The default access level when inviting new members to the portfolio", "type": "string", "enum": [ "admin", "editor", "viewer" ], "example": "viewer" } } } ] }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of custom field settings applied to the portfolio.", "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "description": "The latest `status_update` posted to this portfolio.", "nullable": true } ] }, "custom_fields": { "description": "Array of Custom Fields.", "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "members": { "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "owner": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "description": "*Create-only*. The workspace or organization that the portfolio belongs to." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" }, "public": { "description": "True if the portfolio is public to its workspace members.", "type": "boolean", "example": false }, "privacy_setting": { "description": "The privacy setting of the portfolio. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_domain", "members_only" ], "example": "members_only" }, "project_templates": { "description": "Array of project templates that are in the portfolio", "type": "array", "readOnly": true, "items": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "portfolios:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nPortfolio result = client.portfolios.getPortfolio(portfolioGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfoliosApiInstance = new Asana.PortfoliosApi();\nlet portfolio_gid = \"12345\"; // String | Globally unique identifier for the portfolio.\nlet opts = { \n 'opt_fields': \"archived,color,created_at,created_by,created_by.name,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,due_on,members,members.name,name,owner,owner.name,permalink_url,privacy_setting,project_templates,project_templates.name,public,start_on,workspace,workspace.name\"\n};\nportfoliosApiInstance.getPortfolio(portfolio_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfolios.getPortfolio(portfolioGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolios_api_instance = asana.PortfoliosApi(api_client)\nportfolio_gid = \"12345\" # str | Globally unique identifier for the portfolio.\nopts = {\n 'opt_fields': \"archived,color,created_at,created_by,created_by.name,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,due_on,members,members.name,name,owner,owner.name,permalink_url,privacy_setting,project_templates,project_templates.name,public,start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a portfolio\n api_response = portfolios_api_instance.get_portfolio(portfolio_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling PortfoliosApi->get_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolios.get_portfolio(portfolio_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfolios->getPortfolio($portfolio_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolios.get_portfolio(portfolio_gid: 'portfolio_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a portfolio", "description": "Required scope: portfolios:write\n\nAn existing portfolio can be updated by making a PUT request on the URL for\nthat portfolio. Only the fields provided in the `data` block will be updated;\nany unspecified fields will remain unchanged.\n\nReturns the complete updated portfolio record.", "tags": [ "Portfolios" ], "operationId": "updatePortfolio", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "created_at", "created_by", "created_by.name", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "members", "members.name", "name", "owner", "owner.name", "permalink_url", "privacy_setting", "project_templates", "project_templates.name", "public", "start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "created_at", "created_by", "created_by.name", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "members", "members.name", "name", "owner", "owner.name", "permalink_url", "privacy_setting", "project_templates", "project_templates.name", "public", "start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The updated fields for the portfolio.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, { "type": "object", "properties": { "archived": { "description": "[Opt In](/docs/inputoutput-options). True if the portfolio is archived, false if not. Archived portfolios do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the portfolio.", "type": "string", "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray" ], "example": "light-green" }, "start_on": { "description": "The day on which work for this portfolio begins, or null if the portfolio has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "due_on": { "description": "The day on which this portfolio is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "default_access_level": { "description": "The default access level when inviting new members to the portfolio", "type": "string", "enum": [ "admin", "editor", "viewer" ], "example": "viewer" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "An object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, or object (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.", "type": "object", "additionalProperties": { "type": "string", "description": "\"{custom_field_gid}\" => Value (can be text, enum GID, a number, etc.). For date, use format \"YYYY-MM-DD\" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z)." }, "example": { "5678904321": "On Hold", "4578152156": "Not Started" } } } } ] } } } } } }, "responses": { "200": { "description": "Successfully updated the portfolio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, { "type": "object", "properties": { "archived": { "description": "[Opt In](/docs/inputoutput-options). True if the portfolio is archived, false if not. Archived portfolios do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the portfolio.", "type": "string", "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray" ], "example": "light-green" }, "start_on": { "description": "The day on which work for this portfolio begins, or null if the portfolio has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "due_on": { "description": "The day on which this portfolio is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "default_access_level": { "description": "The default access level when inviting new members to the portfolio", "type": "string", "enum": [ "admin", "editor", "viewer" ], "example": "viewer" } } } ] }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of custom field settings applied to the portfolio.", "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "description": "The latest `status_update` posted to this portfolio.", "nullable": true } ] }, "custom_fields": { "description": "Array of Custom Fields.", "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "members": { "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "owner": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "description": "*Create-only*. The workspace or organization that the portfolio belongs to." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" }, "public": { "description": "True if the portfolio is public to its workspace members.", "type": "boolean", "example": false }, "privacy_setting": { "description": "The privacy setting of the portfolio. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_domain", "members_only" ], "example": "members_only" }, "project_templates": { "description": "Array of project templates that are in the portfolio", "type": "array", "readOnly": true, "items": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "portfolios:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nPortfolio result = client.portfolios.updatePortfolio(portfolioGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfoliosApiInstance = new Asana.PortfoliosApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The updated fields for the portfolio.\nlet portfolio_gid = \"12345\"; // String | Globally unique identifier for the portfolio.\nlet opts = { \n 'opt_fields': \"archived,color,created_at,created_by,created_by.name,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,due_on,members,members.name,name,owner,owner.name,permalink_url,privacy_setting,project_templates,project_templates.name,public,start_on,workspace,workspace.name\"\n};\nportfoliosApiInstance.updatePortfolio(body, portfolio_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfolios.updatePortfolio(portfolioGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolios_api_instance = asana.PortfoliosApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The updated fields for the portfolio.\nportfolio_gid = \"12345\" # str | Globally unique identifier for the portfolio.\nopts = {\n 'opt_fields': \"archived,color,created_at,created_by,created_by.name,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,due_on,members,members.name,name,owner,owner.name,permalink_url,privacy_setting,project_templates,project_templates.name,public,start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a portfolio\n api_response = portfolios_api_instance.update_portfolio(body, portfolio_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling PortfoliosApi->update_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolios.update_portfolio(portfolio_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfolios->updatePortfolio($portfolio_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolios.update_portfolio(portfolio_gid: 'portfolio_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 8, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a portfolio", "description": "An existing portfolio can be deleted by making a DELETE request on\nthe URL for that portfolio.\n\nReturns an empty data record.", "tags": [ "Portfolios" ], "operationId": "deletePortfolio", "responses": { "200": { "description": "Successfully deleted the specified portfolio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.portfolios.deletePortfolio(portfolioGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfoliosApiInstance = new Asana.PortfoliosApi();\nlet portfolio_gid = \"12345\"; // String | Globally unique identifier for the portfolio.\n\nportfoliosApiInstance.deletePortfolio(portfolio_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfolios.deletePortfolio(portfolioGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolios_api_instance = asana.PortfoliosApi(api_client)\nportfolio_gid = \"12345\" # str | Globally unique identifier for the portfolio.\n\n\ntry:\n # Delete a portfolio\n api_response = portfolios_api_instance.delete_portfolio(portfolio_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling PortfoliosApi->delete_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolios.delete_portfolio(portfolio_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfolios->deletePortfolio($portfolio_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolios.delete_portfolio(portfolio_gid: 'portfolio_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/portfolios/{portfolio_gid}/items": { "parameters": [ { "name": "portfolio_gid", "in": "path", "description": "Globally unique identifier for the portfolio.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get portfolio items", "description": "Required scope: portfolios:read\n\nGet a list of the items in compact form in a portfolio.", "tags": [ "Portfolios" ], "operationId": "getItemsForPortfolio", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "offset", "owner", "path", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "offset", "owner", "path", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested portfolio's items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "portfolios:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.portfolios.getItemsForPortfolio(portfolioGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfoliosApiInstance = new Asana.PortfoliosApi();\nlet portfolio_gid = \"12345\"; // String | Globally unique identifier for the portfolio.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,offset,owner,path,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,uri,workspace,workspace.name\"\n};\nportfoliosApiInstance.getItemsForPortfolio(portfolio_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfolios.getItemsForPortfolio(portfolioGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolios_api_instance = asana.PortfoliosApi(api_client)\nportfolio_gid = \"12345\" # str | Globally unique identifier for the portfolio.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,offset,owner,path,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get portfolio items\n api_response = portfolios_api_instance.get_items_for_portfolio(portfolio_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling PortfoliosApi->get_items_for_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolios.get_items_for_portfolio(portfolio_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfolios->getItemsForPortfolio($portfolio_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolios.get_items_for_portfolio(portfolio_gid: 'portfolio_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/portfolios/{portfolio_gid}/addItem": { "parameters": [ { "name": "portfolio_gid", "in": "path", "description": "Globally unique identifier for the portfolio.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add a portfolio item", "description": "Required scope: portfolios:write\n\nAdd an item to a portfolio.\nReturns an empty data block.", "tags": [ "Portfolios" ], "operationId": "addItemForPortfolio", "requestBody": { "description": "Information about the item being inserted.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "item" ], "properties": { "item": { "description": "The item to add to the portfolio.", "type": "string", "example": "1331" }, "insert_before": { "description": "An id of an item in this portfolio. The new item will be added before the one specified here. `insert_before` and `insert_after` parameters cannot both be specified.", "type": "string", "example": "1331" }, "insert_after": { "description": "An id of an item in this portfolio. The new item will be added after the one specified here. `insert_before` and `insert_after` parameters cannot both be specified.", "type": "string", "example": "1331" } } } } } } } }, "responses": { "200": { "description": "Successfully added the item to the portfolio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "portfolios:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.portfolios.addItemForPortfolio(portfolioGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfoliosApiInstance = new Asana.PortfoliosApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the item being inserted.\nlet portfolio_gid = \"12345\"; // String | Globally unique identifier for the portfolio.\n\nportfoliosApiInstance.addItemForPortfolio(body, portfolio_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfolios.addItemForPortfolio(portfolioGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolios_api_instance = asana.PortfoliosApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the item being inserted.\nportfolio_gid = \"12345\" # str | Globally unique identifier for the portfolio.\n\n\ntry:\n # Add a portfolio item\n api_response = portfolios_api_instance.add_item_for_portfolio(body, portfolio_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling PortfoliosApi->add_item_for_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolios.add_item_for_portfolio(portfolio_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfolios->addItemForPortfolio($portfolio_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolios.add_item_for_portfolio(portfolio_gid: 'portfolio_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 3, "x-moar-complexity-skipped": false } }, "/portfolios/{portfolio_gid}/removeItem": { "parameters": [ { "name": "portfolio_gid", "in": "path", "description": "Globally unique identifier for the portfolio.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Remove a portfolio item", "description": "Required scope: portfolios:write\n\nRemove an item from a portfolio.\nReturns an empty data block.", "tags": [ "Portfolios" ], "operationId": "removeItemForPortfolio", "requestBody": { "description": "Information about the item being removed.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "item" ], "properties": { "item": { "description": "The item to remove from the portfolio.", "type": "string", "example": "1331" } } } } } } } }, "responses": { "200": { "description": "Successfully removed the item from the portfolio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "portfolios:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.portfolios.removeItemForPortfolio(portfolioGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfoliosApiInstance = new Asana.PortfoliosApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the item being removed.\nlet portfolio_gid = \"12345\"; // String | Globally unique identifier for the portfolio.\n\nportfoliosApiInstance.removeItemForPortfolio(body, portfolio_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfolios.removeItemForPortfolio(portfolioGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolios_api_instance = asana.PortfoliosApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the item being removed.\nportfolio_gid = \"12345\" # str | Globally unique identifier for the portfolio.\n\n\ntry:\n # Remove a portfolio item\n api_response = portfolios_api_instance.remove_item_for_portfolio(body, portfolio_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling PortfoliosApi->remove_item_for_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolios.remove_item_for_portfolio(portfolio_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfolios->removeItemForPortfolio($portfolio_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolios.remove_item_for_portfolio(portfolio_gid: 'portfolio_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/portfolios/{portfolio_gid}/addCustomFieldSetting": { "parameters": [ { "name": "portfolio_gid", "in": "path", "description": "Globally unique identifier for the portfolio.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add a custom field to a portfolio", "description": "Required scope: portfolios:write\n\nCustom fields are associated with portfolios by way of custom field settings. This method creates a setting for the portfolio.", "tags": [ "Portfolios" ], "operationId": "addCustomFieldSettingForPortfolio", "security": [ { "oauth2": [ "portfolios:write" ] } ], "requestBody": { "description": "Information about the custom field setting.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "custom_field" ], "properties": { "custom_field": { "oneOf": [ { "type": "string", "description": "The custom field to associate with this container.", "example": "14916" }, { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "required": [ "workspace" ], "properties": { "workspace": { "type": "string", "description": "*Create-Only* The workspace to create a custom field in.", "example": "1331" }, "owned_by_app": { "type": "boolean", "description": "*Allow-listed*. Instructs the API that this Custom Field is app-owned. This parameter is allow-listed to specific apps at this point in time. For apps that are not allow-listed, providing this parameter will result in a `403 Forbidden`." }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of user GIDs reflects the users to be written to a `people` custom field. Note that *write* operations will replace existing users (if any) in the custom field with the users specified in this array.", "type": "array", "items": { "type": "string", "description": "The GID of a user." }, "example": [ "12345" ] }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of GIDs reflects the objects to be written to a `reference` custom field. Note that *write* operations will replace existing objects (if any) in the custom field with the objects specified in this array.", "type": "array", "items": { "type": "string", "description": "The GID of an object." }, "example": [ "12345" ] } } } ] }, { "type": "object", "required": [ "resource_subtype" ], "properties": { "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.", "type": "string", "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] } ] }, "is_important": { "description": "Whether this field should be considered important to this container (for instance, to display in the list view of items in the container).", "type": "boolean", "example": true }, "insert_before": { "description": "A gid of a Custom Field Setting on this container, before which the new Custom Field Setting will be added. `insert_before` and `insert_after` parameters cannot both be specified.", "type": "string", "example": "1331" }, "insert_after": { "description": "A gid of a Custom Field Setting on this container, after which the new Custom Field Setting will be added. `insert_before` and `insert_after` parameters cannot both be specified.", "type": "string", "example": "1331" } } } } } } } }, "responses": { "200": { "description": "Successfully added the custom field to the portfolio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nCustomFieldSetting result = client.portfolios.addCustomFieldSettingForPortfolio(portfolioGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfoliosApiInstance = new Asana.PortfoliosApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the custom field setting.\nlet portfolio_gid = \"12345\"; // String | Globally unique identifier for the portfolio.\n\nportfoliosApiInstance.addCustomFieldSettingForPortfolio(body, portfolio_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfolios.addCustomFieldSettingForPortfolio(portfolioGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolios_api_instance = asana.PortfoliosApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the custom field setting.\nportfolio_gid = \"12345\" # str | Globally unique identifier for the portfolio.\n\n\ntry:\n # Add a custom field to a portfolio\n api_response = portfolios_api_instance.add_custom_field_setting_for_portfolio(body, portfolio_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling PortfoliosApi->add_custom_field_setting_for_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolios.add_custom_field_setting_for_portfolio(portfolio_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfolios->addCustomFieldSettingForPortfolio($portfolio_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolios.add_custom_field_setting_for_portfolio(portfolio_gid: 'portfolio_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 52, "x-moar-complexity-skipped": false } }, "/portfolios/{portfolio_gid}/removeCustomFieldSetting": { "parameters": [ { "name": "portfolio_gid", "in": "path", "description": "Globally unique identifier for the portfolio.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Remove a custom field from a portfolio", "description": "Required scope: portfolios:write\n\nRemoves a custom field setting from a portfolio.", "tags": [ "Portfolios" ], "operationId": "removeCustomFieldSettingForPortfolio", "security": [ { "oauth2": [ "portfolios:write" ] } ], "requestBody": { "description": "Information about the custom field setting being removed.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "custom_field" ], "properties": { "custom_field": { "description": "The custom field to remove from this portfolio.", "type": "string", "example": "14916" } } } } } } } }, "responses": { "200": { "description": "Successfully removed the custom field from the portfolio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.portfolios.removeCustomFieldSettingForPortfolio(portfolioGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfoliosApiInstance = new Asana.PortfoliosApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the custom field setting being removed.\nlet portfolio_gid = \"12345\"; // String | Globally unique identifier for the portfolio.\n\nportfoliosApiInstance.removeCustomFieldSettingForPortfolio(body, portfolio_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfolios.removeCustomFieldSettingForPortfolio(portfolioGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolios_api_instance = asana.PortfoliosApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the custom field setting being removed.\nportfolio_gid = \"12345\" # str | Globally unique identifier for the portfolio.\n\n\ntry:\n # Remove a custom field from a portfolio\n api_response = portfolios_api_instance.remove_custom_field_setting_for_portfolio(body, portfolio_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling PortfoliosApi->remove_custom_field_setting_for_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolios.remove_custom_field_setting_for_portfolio(portfolio_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfolios->removeCustomFieldSettingForPortfolio($portfolio_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolios.remove_custom_field_setting_for_portfolio(portfolio_gid: 'portfolio_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/portfolios/{portfolio_gid}/addMembers": { "parameters": [ { "name": "portfolio_gid", "in": "path", "description": "Globally unique identifier for the portfolio.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add users to a portfolio", "description": "Adds the specified list of users as members of the portfolio.\nReturns the updated portfolio record.", "tags": [ "Portfolios" ], "operationId": "addMembersForPortfolio", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "created_at", "created_by", "created_by.name", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "members", "members.name", "name", "owner", "owner.name", "permalink_url", "privacy_setting", "project_templates", "project_templates.name", "public", "start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "created_at", "created_by", "created_by.name", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "members", "members.name", "name", "owner", "owner.name", "permalink_url", "privacy_setting", "project_templates", "project_templates.name", "public", "start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Information about the members being added.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "members" ], "properties": { "members": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "521621,621373" } } } } } } } }, "responses": { "200": { "description": "Successfully added members to the portfolio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, { "type": "object", "properties": { "archived": { "description": "[Opt In](/docs/inputoutput-options). True if the portfolio is archived, false if not. Archived portfolios do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the portfolio.", "type": "string", "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray" ], "example": "light-green" }, "start_on": { "description": "The day on which work for this portfolio begins, or null if the portfolio has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "due_on": { "description": "The day on which this portfolio is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "default_access_level": { "description": "The default access level when inviting new members to the portfolio", "type": "string", "enum": [ "admin", "editor", "viewer" ], "example": "viewer" } } } ] }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of custom field settings applied to the portfolio.", "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "description": "The latest `status_update` posted to this portfolio.", "nullable": true } ] }, "custom_fields": { "description": "Array of Custom Fields.", "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "members": { "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "owner": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "description": "*Create-only*. The workspace or organization that the portfolio belongs to." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" }, "public": { "description": "True if the portfolio is public to its workspace members.", "type": "boolean", "example": false }, "privacy_setting": { "description": "The privacy setting of the portfolio. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_domain", "members_only" ], "example": "members_only" }, "project_templates": { "description": "Array of project templates that are in the portfolio", "type": "array", "readOnly": true, "items": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nPortfolio result = client.portfolios.addMembersForPortfolio(portfolioGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfoliosApiInstance = new Asana.PortfoliosApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the members being added.\nlet portfolio_gid = \"12345\"; // String | Globally unique identifier for the portfolio.\nlet opts = { \n 'opt_fields': \"archived,color,created_at,created_by,created_by.name,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,due_on,members,members.name,name,owner,owner.name,permalink_url,privacy_setting,project_templates,project_templates.name,public,start_on,workspace,workspace.name\"\n};\nportfoliosApiInstance.addMembersForPortfolio(body, portfolio_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfolios.addMembersForPortfolio(portfolioGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolios_api_instance = asana.PortfoliosApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the members being added.\nportfolio_gid = \"12345\" # str | Globally unique identifier for the portfolio.\nopts = {\n 'opt_fields': \"archived,color,created_at,created_by,created_by.name,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,due_on,members,members.name,name,owner,owner.name,permalink_url,privacy_setting,project_templates,project_templates.name,public,start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Add users to a portfolio\n api_response = portfolios_api_instance.add_members_for_portfolio(body, portfolio_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling PortfoliosApi->add_members_for_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolios.add_members_for_portfolio(portfolio_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfolios->addMembersForPortfolio($portfolio_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolios.add_members_for_portfolio(portfolio_gid: 'portfolio_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/portfolios/{portfolio_gid}/removeMembers": { "parameters": [ { "name": "portfolio_gid", "in": "path", "description": "Globally unique identifier for the portfolio.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "portfolio" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Remove users from a portfolio", "description": "Removes the specified list of users from members of the portfolio.\nReturns the updated portfolio record.", "tags": [ "Portfolios" ], "operationId": "removeMembersForPortfolio", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "created_at", "created_by", "created_by.name", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "members", "members.name", "name", "owner", "owner.name", "permalink_url", "privacy_setting", "project_templates", "project_templates.name", "public", "start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "created_at", "created_by", "created_by.name", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "due_on", "members", "members.name", "name", "owner", "owner.name", "permalink_url", "privacy_setting", "project_templates", "project_templates.name", "public", "start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Information about the members being removed.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "members" ], "properties": { "members": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "521621,621373" } } } } } } } }, "responses": { "200": { "description": "Successfully removed the members from the portfolio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *portfolio* gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple projects, including a progress report and the most recent [project status](/reference/project-statuses) update.\nPortfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a max of 20 custom fields.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "portfolio", "x-insert-after": "gid" }, "name": { "description": "The name of the portfolio.", "type": "string", "example": "Bug Portfolio" } } }, { "type": "object", "properties": { "archived": { "description": "[Opt In](/docs/inputoutput-options). True if the portfolio is archived, false if not. Archived portfolios do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the portfolio.", "type": "string", "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray" ], "example": "light-green" }, "start_on": { "description": "The day on which work for this portfolio begins, or null if the portfolio has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "due_on": { "description": "The day on which this portfolio is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "default_access_level": { "description": "The default access level when inviting new members to the portfolio", "type": "string", "enum": [ "admin", "editor", "viewer" ], "example": "viewer" } } } ] }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of custom field settings applied to the portfolio.", "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "description": "The latest `status_update` posted to this portfolio.", "nullable": true } ] }, "custom_fields": { "description": "Array of Custom Fields.", "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "members": { "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "owner": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "description": "*Create-only*. The workspace or organization that the portfolio belongs to." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" }, "public": { "description": "True if the portfolio is public to its workspace members.", "type": "boolean", "example": false }, "privacy_setting": { "description": "The privacy setting of the portfolio. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_domain", "members_only" ], "example": "members_only" }, "project_templates": { "description": "Array of project templates that are in the portfolio", "type": "array", "readOnly": true, "items": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nPortfolio result = client.portfolios.removeMembersForPortfolio(portfolioGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet portfoliosApiInstance = new Asana.PortfoliosApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the members being removed.\nlet portfolio_gid = \"12345\"; // String | Globally unique identifier for the portfolio.\nlet opts = { \n 'opt_fields': \"archived,color,created_at,created_by,created_by.name,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,due_on,members,members.name,name,owner,owner.name,permalink_url,privacy_setting,project_templates,project_templates.name,public,start_on,workspace,workspace.name\"\n};\nportfoliosApiInstance.removeMembersForPortfolio(body, portfolio_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.portfolios.removeMembersForPortfolio(portfolioGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nportfolios_api_instance = asana.PortfoliosApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the members being removed.\nportfolio_gid = \"12345\" # str | Globally unique identifier for the portfolio.\nopts = {\n 'opt_fields': \"archived,color,created_at,created_by,created_by.name,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,due_on,members,members.name,name,owner,owner.name,permalink_url,privacy_setting,project_templates,project_templates.name,public,start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Remove users from a portfolio\n api_response = portfolios_api_instance.remove_members_for_portfolio(body, portfolio_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling PortfoliosApi->remove_members_for_portfolio: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.portfolios.remove_members_for_portfolio(portfolio_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "portfolios->removeMembersForPortfolio($portfolio_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.portfolios.remove_members_for_portfolio(portfolio_gid: 'portfolio_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/project_briefs/{project_brief_gid}": { "parameters": [ { "name": "project_brief_gid", "in": "path", "description": "Globally unique identifier for the project brief.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "project_brief" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a project brief", "description": "Get the full record for a project brief.", "tags": [ "Project briefs" ], "operationId": "getProjectBrief", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "html_text", "permalink_url", "project", "project.name", "text", "title" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "html_text", "permalink_url", "project", "project.name", "text", "title" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the record for a project brief.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "title": { "description": "The title of the project brief.", "type": "string", "example": "Stuff to buy \u2014 Project Brief" }, "html_text": { "description": "HTML formatted text for the project brief.", "type": "string", "example": "This is a project brief." } } } ] }, { "type": "object", "properties": { "text": { "description": "[Opt In](/docs/inputoutput-options). The plain text of the project brief.", "type": "string", "example": "This is a project brief." }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/11111111/22222222" }, "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The project with which this project brief is associated." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "424": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "501": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.projectbriefs.getProjectBrief(projectBriefGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectBriefsApiInstance = new Asana.ProjectBriefsApi();\nlet project_brief_gid = \"12345\"; // String | Globally unique identifier for the project brief.\nlet opts = { \n 'opt_fields': \"html_text,permalink_url,project,project.name,text,title\"\n};\nprojectBriefsApiInstance.getProjectBrief(project_brief_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projectbriefs.getProjectBrief(projectBriefGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_briefs_api_instance = asana.ProjectBriefsApi(api_client)\nproject_brief_gid = \"12345\" # str | Globally unique identifier for the project brief.\nopts = {\n 'opt_fields': \"html_text,permalink_url,project,project.name,text,title\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a project brief\n api_response = project_briefs_api_instance.get_project_brief(project_brief_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectBriefsApi->get_project_brief: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_briefs.get_project_brief(project_brief_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projectbriefs->getProjectBrief($project_brief_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_briefs.get_project_brief(project_brief_gid: 'project_brief_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a project brief", "description": "An existing project brief can be updated by making a PUT request on the URL for\nthat project brief. Only the fields provided in the `data` block will be updated;\nany unspecified fields will remain unchanged.\n\nReturns the complete updated project brief record.", "tags": [ "Project briefs" ], "operationId": "updateProjectBrief", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "html_text", "permalink_url", "project", "project.name", "text", "title" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "html_text", "permalink_url", "project", "project.name", "text", "title" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The updated fields for the project brief.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "title": { "description": "The title of the project brief.", "type": "string", "example": "Stuff to buy \u2014 Project Brief" }, "html_text": { "description": "HTML formatted text for the project brief.", "type": "string", "example": "This is a project brief." } } } ] }, { "type": "object", "properties": { "text": { "description": "The plain text of the project brief. When writing to a project brief, you can specify either `html_text` (preferred) or `text`, but not both.", "type": "string", "example": "This is a project brief." } } } ] } } } } } }, "responses": { "200": { "description": "Successfully updated the project brief.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "title": { "description": "The title of the project brief.", "type": "string", "example": "Stuff to buy \u2014 Project Brief" }, "html_text": { "description": "HTML formatted text for the project brief.", "type": "string", "example": "This is a project brief." } } } ] }, { "type": "object", "properties": { "text": { "description": "[Opt In](/docs/inputoutput-options). The plain text of the project brief.", "type": "string", "example": "This is a project brief." }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/11111111/22222222" }, "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The project with which this project brief is associated." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.projectbriefs.updateProjectBrief(projectBriefGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectBriefsApiInstance = new Asana.ProjectBriefsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The updated fields for the project brief.\nlet project_brief_gid = \"12345\"; // String | Globally unique identifier for the project brief.\nlet opts = { \n 'opt_fields': \"html_text,permalink_url,project,project.name,text,title\"\n};\nprojectBriefsApiInstance.updateProjectBrief(body, project_brief_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projectbriefs.updateProjectBrief(projectBriefGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_briefs_api_instance = asana.ProjectBriefsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The updated fields for the project brief.\nproject_brief_gid = \"12345\" # str | Globally unique identifier for the project brief.\nopts = {\n 'opt_fields': \"html_text,permalink_url,project,project.name,text,title\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a project brief\n api_response = project_briefs_api_instance.update_project_brief(body, project_brief_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectBriefsApi->update_project_brief: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_briefs.update_project_brief(project_brief_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projectbriefs->updateProjectBrief($project_brief_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_briefs.update_project_brief(project_brief_gid: 'project_brief_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 5, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a project brief", "description": "Deletes a specific, existing project brief.\n\nReturns an empty data record.", "tags": [ "Project briefs" ], "operationId": "deleteProjectBrief", "responses": { "200": { "description": "Successfully deleted the specified project brief.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.projectbriefs.deleteProjectBrief(projectBriefGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectBriefsApiInstance = new Asana.ProjectBriefsApi();\nlet project_brief_gid = \"12345\"; // String | Globally unique identifier for the project brief.\n\nprojectBriefsApiInstance.deleteProjectBrief(project_brief_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projectbriefs.deleteProjectBrief(projectBriefGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_briefs_api_instance = asana.ProjectBriefsApi(api_client)\nproject_brief_gid = \"12345\" # str | Globally unique identifier for the project brief.\n\n\ntry:\n # Delete a project brief\n api_response = project_briefs_api_instance.delete_project_brief(project_brief_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectBriefsApi->delete_project_brief: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_briefs.delete_project_brief(project_brief_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projectbriefs->deleteProjectBrief($project_brief_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_briefs.delete_project_brief(project_brief_gid: 'project_brief_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/project_briefs": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Create a project brief", "description": "Creates a new project brief.\n\nReturns the full record of the newly created project brief.", "tags": [ "Project briefs" ], "operationId": "createProjectBrief", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "html_text", "permalink_url", "project", "project.name", "text", "title" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "html_text", "permalink_url", "project", "project.name", "text", "title" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The project brief to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "title": { "description": "The title of the project brief.", "type": "string", "example": "Stuff to buy \u2014 Project Brief" }, "html_text": { "description": "HTML formatted text for the project brief.", "type": "string", "example": "This is a project brief." } } } ] }, { "type": "object", "properties": { "text": { "description": "The plain text of the project brief. When writing to a project brief, you can specify either `html_text` (preferred) or `text`, but not both.", "type": "string", "example": "This is a project brief." } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created a new project brief.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "title": { "description": "The title of the project brief.", "type": "string", "example": "Stuff to buy \u2014 Project Brief" }, "html_text": { "description": "HTML formatted text for the project brief.", "type": "string", "example": "This is a project brief." } } } ] }, { "type": "object", "properties": { "text": { "description": "[Opt In](/docs/inputoutput-options). The plain text of the project brief.", "type": "string", "example": "This is a project brief." }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/11111111/22222222" }, "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The project with which this project brief is associated." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.projectbriefs.createProjectBrief(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectBriefsApiInstance = new Asana.ProjectBriefsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The project brief to create.\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'opt_fields': \"html_text,permalink_url,project,project.name,text,title\"\n};\nprojectBriefsApiInstance.createProjectBrief(body, project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projectbriefs.createProjectBrief(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_briefs_api_instance = asana.ProjectBriefsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The project brief to create.\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'opt_fields': \"html_text,permalink_url,project,project.name,text,title\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a project brief\n api_response = project_briefs_api_instance.create_project_brief(body, project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectBriefsApi->create_project_brief: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_briefs.create_project_brief(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projectbriefs->createProjectBrief($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_briefs.create_project_brief(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 5, "x-moar-complexity-skipped": false } }, "/project_memberships/{project_membership_gid}": { "parameters": [ { "name": "project_membership_gid", "in": "path", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project_membership" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a project membership", "description": "Returns the complete project record for a single project membership.", "tags": [ "Project memberships" ], "operationId": "getProjectMembership", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "access_level", "member", "member.name", "parent", "parent.name", "project", "project.name", "user", "user.name", "write_access" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "access_level", "member", "member.name", "parent", "parent.name", "project", "project.name", "user", "user.name", "write_access" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested project membership.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "This object describes a team or a user's membership to a project including their level of access (Admin, Editor, Commenter, or Viewer).", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_membership", "x-insert-after": "gid" }, "parent": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, commenter, or viewer access to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "readOnly": true, "example": "admin" } } }, { "type": "object", "properties": { "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "resource_type": { "description": "The base type of this resource.", "type": "string", "example": "project_membership" }, "write_access": { "description": "Whether the member has full access or comment-only access to the project.", "type": "string", "enum": [ "full_write", "comment_only" ], "readOnly": true, "example": "full_write" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nProjectMembership result = client.projectmemberships.getProjectMembership(projectMembershipGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectMembershipsApiInstance = new Asana.ProjectMembershipsApi();\nlet project_membership_gid = \"1331\"; // String | \nlet opts = { \n 'opt_fields': \"access_level,member,member.name,parent,parent.name,project,project.name,user,user.name,write_access\"\n};\nprojectMembershipsApiInstance.getProjectMembership(project_membership_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projectmemberships.getProjectMembership(projectMembershipGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_memberships_api_instance = asana.ProjectMembershipsApi(api_client)\nproject_membership_gid = \"1331\" # str | \nopts = {\n 'opt_fields': \"access_level,member,member.name,parent,parent.name,project,project.name,user,user.name,write_access\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a project membership\n api_response = project_memberships_api_instance.get_project_membership(project_membership_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectMembershipsApi->get_project_membership: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_memberships.get_project_membership(project_membership_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projectmemberships->getProjectMembership($project_membership_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_memberships.get_project_membership(project_membership_gid: 'project_membership_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/project_memberships": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "user", "in": "query", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get memberships from a project", "description": "Returns the compact project membership records for the project.", "tags": [ "Project memberships" ], "operationId": "getProjectMembershipsForProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "access_level", "member", "member.name", "offset", "parent", "parent.name", "path", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "access_level", "member", "member.name", "offset", "parent", "parent.name", "path", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested project's memberships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "This object describes a team or a user's membership to a project including their level of access (Admin, Editor, Commenter, or Viewer).", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_membership", "x-insert-after": "gid" }, "parent": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "member": { "description": "A *member* object represents either a team or user.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "type": "string", "description": "The type of the member (team or user)", "example": "user" }, "name": { "type": "string", "description": "The name of the member", "example": "Greg Sanchez" } } }, "access_level": { "description": "Whether the member has admin, editor, commenter, or viewer access to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "readOnly": true, "example": "admin" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.projectmemberships.getProjectMembershipsForProject(projectGid, user)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectMembershipsApiInstance = new Asana.ProjectMembershipsApi();\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'user': \"me\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"access_level,member,member.name,offset,parent,parent.name,path,uri\"\n};\nprojectMembershipsApiInstance.getProjectMembershipsForProject(project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projectmemberships.getProjectMembershipsForProject(projectGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_memberships_api_instance = asana.ProjectMembershipsApi(api_client)\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'user': \"me\", # str | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"access_level,member,member.name,offset,parent,parent.name,path,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get memberships from a project\n api_response = project_memberships_api_instance.get_project_memberships_for_project(project_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling ProjectMembershipsApi->get_project_memberships_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_memberships.get_project_memberships_for_project(project_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projectmemberships->getProjectMembershipsForProject($project_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_memberships.get_project_memberships_for_project(project_gid: 'project_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/project_statuses/{project_status_gid}": { "parameters": [ { "name": "project_status_gid", "in": "path", "required": true, "description": "The project status update to get.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "project_status" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a project status", "description": "*Deprecated: new integrations should prefer the `/status_updates/{status_gid}` route.*\n\nReturns the complete record for a single status update.", "tags": [ "Project statuses" ], "operationId": "getProjectStatus", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "author", "author.name", "color", "created_at", "created_by", "created_by.name", "html_text", "modified_at", "text", "title" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "author", "author.name", "color", "created_at", "created_by", "created_by.name", "html_text", "modified_at", "text", "title" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified project's status updates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nProjectStatus result = client.projectstatuses.getProjectStatus(projectStatusGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectStatusesApiInstance = new Asana.ProjectStatusesApi();\nlet project_status_gid = \"321654\"; // String | The project status update to get.\nlet opts = { \n 'opt_fields': \"author,author.name,color,created_at,created_by,created_by.name,html_text,modified_at,text,title\"\n};\nprojectStatusesApiInstance.getProjectStatus(project_status_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projectstatuses.getProjectStatus(projectStatusGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_statuses_api_instance = asana.ProjectStatusesApi(api_client)\nproject_status_gid = \"321654\" # str | The project status update to get.\nopts = {\n 'opt_fields': \"author,author.name,color,created_at,created_by,created_by.name,html_text,modified_at,text,title\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a project status\n api_response = project_statuses_api_instance.get_project_status(project_status_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectStatusesApi->get_project_status: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_statuses.get_project_status(project_status_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projectstatuses->getProjectStatus($project_status_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_statuses.get_project_status(project_status_gid: 'project_status_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a project status", "description": "*Deprecated: new integrations should prefer the `/status_updates/{status_gid}` route.*\n\nDeletes a specific, existing project status update.\n\nReturns an empty data record.", "tags": [ "Project statuses" ], "operationId": "deleteProjectStatus", "responses": { "200": { "description": "Successfully deleted the specified project status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.projectstatuses.deleteProjectStatus(projectStatusGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectStatusesApiInstance = new Asana.ProjectStatusesApi();\nlet project_status_gid = \"321654\"; // String | The project status update to get.\n\nprojectStatusesApiInstance.deleteProjectStatus(project_status_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projectstatuses.deleteProjectStatus(projectStatusGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_statuses_api_instance = asana.ProjectStatusesApi(api_client)\nproject_status_gid = \"321654\" # str | The project status update to get.\n\n\ntry:\n # Delete a project status\n api_response = project_statuses_api_instance.delete_project_status(project_status_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectStatusesApi->delete_project_status: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_statuses.delete_project_status(project_status_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projectstatuses->deleteProjectStatus($project_status_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_statuses.delete_project_status(project_status_gid: 'project_status_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/project_statuses": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get statuses from a project", "description": "*Deprecated: new integrations should prefer the `/status_updates` route.*\n\nReturns the compact project status update records for all updates on the project.", "tags": [ "Project statuses" ], "operationId": "getProjectStatusesForProject", "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "author", "author.name", "color", "created_at", "created_by", "created_by.name", "html_text", "modified_at", "offset", "path", "text", "title", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "author", "author.name", "color", "created_at", "created_by", "created_by.name", "html_text", "modified_at", "offset", "path", "text", "title", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified project's status updates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.projectstatuses.getProjectStatusesForProject(projectGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectStatusesApiInstance = new Asana.ProjectStatusesApi();\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"author,author.name,color,created_at,created_by,created_by.name,html_text,modified_at,offset,path,text,title,uri\"\n};\nprojectStatusesApiInstance.getProjectStatusesForProject(project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projectstatuses.getProjectStatusesForProject(projectGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_statuses_api_instance = asana.ProjectStatusesApi(api_client)\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"author,author.name,color,created_at,created_by,created_by.name,html_text,modified_at,offset,path,text,title,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get statuses from a project\n api_response = project_statuses_api_instance.get_project_statuses_for_project(project_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling ProjectStatusesApi->get_project_statuses_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_statuses.get_project_statuses_for_project(project_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projectstatuses->getProjectStatusesForProject($project_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_statuses.get_project_statuses_for_project(project_gid: 'project_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a project status", "description": "*Deprecated: new integrations should prefer the `/status_updates` route.*\n\nCreates a new status update on the project.\n\nReturns the full record of the newly created project status update.", "tags": [ "Project statuses" ], "operationId": "createProjectStatusForProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "author", "author.name", "color", "created_at", "created_by", "created_by.name", "html_text", "modified_at", "text", "title" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "author", "author.name", "color", "created_at", "created_by", "created_by.name", "html_text", "modified_at", "text", "title" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The project status to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created a new story.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nProjectStatus result = client.projectstatuses.createProjectStatusForProject(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectStatusesApiInstance = new Asana.ProjectStatusesApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The project status to create.\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'opt_fields': \"author,author.name,color,created_at,created_by,created_by.name,html_text,modified_at,text,title\"\n};\nprojectStatusesApiInstance.createProjectStatusForProject(body, project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projectstatuses.createProjectStatusForProject(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_statuses_api_instance = asana.ProjectStatusesApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The project status to create.\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'opt_fields': \"author,author.name,color,created_at,created_by,created_by.name,html_text,modified_at,text,title\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a project status\n api_response = project_statuses_api_instance.create_project_status_for_project(body, project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectStatusesApi->create_project_status_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_statuses.create_project_status_for_project(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projectstatuses->createProjectStatusForProject($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_statuses.create_project_status_for_project(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 6, "x-moar-complexity-skipped": false } }, "/project_templates/{project_template_gid}": { "parameters": [ { "name": "project_template_gid", "in": "path", "description": "Globally unique identifier for the project template.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project_template" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a project template", "description": "Required scope: project_templates:read\n\nReturns the complete project template record for a single project template.", "tags": [ "Project templates" ], "operationId": "getProjectTemplate", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "description", "html_description", "name", "owner", "public", "requested_dates", "requested_dates.description", "requested_dates.name", "requested_roles", "requested_roles.name", "team", "team.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "description", "html_description", "name", "owner", "public", "requested_dates", "requested_dates.description", "requested_dates.name", "requested_roles", "requested_roles.name", "team", "team.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested project template.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, { "type": "object", "properties": { "description": { "description": "Free-form textual information associated with the project template", "type": "string", "example": "These are things we need to pack for a trip." }, "html_description": { "description": "The description of the project template with formatting as HTML.", "type": "string", "example": "These are things we need to pack for a trip." }, "public": { "description": "True if the project template is public to its team.", "type": "boolean", "example": false }, "owner": { "description": "The current owner of the project template, may be null.", "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } } ] }, "requested_dates": { "description": "Array of date variables in this project template. Calendar dates must be provided for these variables when instantiating a project.", "type": "array", "items": { "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the date field in the project template. A value of `1` refers to the project start date, while `2` refers to the project due date.", "type": "string", "readOnly": true, "example": "1" }, "name": { "description": "The name of the date variable.", "type": "string", "readOnly": true, "example": "Start Date" }, "description": { "description": "The description of what the date variable is used for when instantiating a project.", "type": "string", "readOnly": true, "example": "Choose a start date for your project." } } }, "readOnly": true }, "color": { "description": "Color of the project template.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", null ], "example": "light-green" }, "requested_roles": { "description": "Array of template roles in this project template. User Ids can be provided for these variables when instantiating a project to assign template tasks to the user.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "type": "string", "description": "Name of the template role.", "example": "Designer" } } } } } } ] } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "project_templates:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.projecttemplates.getProjectTemplate(projectTemplateGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectTemplatesApiInstance = new Asana.ProjectTemplatesApi();\nlet project_template_gid = \"1331\"; // String | Globally unique identifier for the project template.\nlet opts = { \n 'opt_fields': \"color,description,html_description,name,owner,public,requested_dates,requested_dates.description,requested_dates.name,requested_roles,requested_roles.name,team,team.name\"\n};\nprojectTemplatesApiInstance.getProjectTemplate(project_template_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projecttemplates.getProjectTemplate(projectTemplateGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_templates_api_instance = asana.ProjectTemplatesApi(api_client)\nproject_template_gid = \"1331\" # str | Globally unique identifier for the project template.\nopts = {\n 'opt_fields': \"color,description,html_description,name,owner,public,requested_dates,requested_dates.description,requested_dates.name,requested_roles,requested_roles.name,team,team.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a project template\n api_response = project_templates_api_instance.get_project_template(project_template_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectTemplatesApi->get_project_template: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_templates.get_project_template(project_template_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projecttemplates->getProjectTemplate($project_template_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_templates.get_project_template(project_template_gid: 'project_template_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a project template", "description": "A specific, existing project template can be deleted by making a DELETE request on the URL for that project template.\n\nReturns an empty data record.", "tags": [ "Project templates" ], "operationId": "deleteProjectTemplate", "responses": { "200": { "description": "Successfully deleted the specified project template.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectTemplatesApiInstance = new Asana.ProjectTemplatesApi();\nlet project_template_gid = \"1331\"; // String | Globally unique identifier for the project template.\n\nprojectTemplatesApiInstance.deleteProjectTemplate(project_template_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projecttemplates.deleteProjectTemplate(projectTemplateGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_templates_api_instance = asana.ProjectTemplatesApi(api_client)\nproject_template_gid = \"1331\" # str | Globally unique identifier for the project template.\n\n\ntry:\n # Delete a project template\n api_response = project_templates_api_instance.delete_project_template(project_template_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectTemplatesApi->delete_project_template: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_templates.delete_project_template(project_template_gid, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/project_templates": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get multiple project templates", "description": "Required scope: project_templates:read\n\nReturns the compact project template records for all project templates in the given team or workspace.", "tags": [ "Project templates" ], "operationId": "getProjectTemplates", "parameters": [ { "name": "workspace", "in": "query", "description": "The workspace to filter results on.", "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "team", "in": "query", "description": "The team to filter projects on.", "schema": { "type": "string" }, "example": "14916", "x-env-variable": "team" }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "description", "html_description", "name", "offset", "owner", "path", "public", "requested_dates", "requested_dates.description", "requested_dates.name", "requested_roles", "requested_roles.name", "team", "team.name", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "description", "html_description", "name", "offset", "owner", "path", "public", "requested_dates", "requested_dates.description", "requested_dates.name", "requested_roles", "requested_roles.name", "team", "team.name", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested team's or workspace's project templates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "project_templates:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.projecttemplates.getProjectTemplates(team, workspace)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectTemplatesApiInstance = new Asana.ProjectTemplatesApi();\nlet opts = { \n 'workspace': \"12345\", \n 'team': \"14916\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"color,description,html_description,name,offset,owner,path,public,requested_dates,requested_dates.description,requested_dates.name,requested_roles,requested_roles.name,team,team.name,uri\"\n};\nprojectTemplatesApiInstance.getProjectTemplates(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projecttemplates.getProjectTemplates({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_templates_api_instance = asana.ProjectTemplatesApi(api_client)\nopts = {\n 'workspace': \"12345\", # str | The workspace to filter results on.\n 'team': \"14916\", # str | The team to filter projects on.\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"color,description,html_description,name,offset,owner,path,public,requested_dates,requested_dates.description,requested_dates.name,requested_roles,requested_roles.name,team,team.name,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple project templates\n api_response = project_templates_api_instance.get_project_templates(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling ProjectTemplatesApi->get_project_templates: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_templates.get_project_templates({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projecttemplates->getProjectTemplates(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_templates.get_project_templates(param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/teams/{team_gid}/project_templates": { "parameters": [ { "name": "team_gid", "in": "path", "description": "Globally unique identifier for the team.", "required": true, "schema": { "type": "string" }, "example": "159874", "x-env-variable": "team" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a team's project templates", "description": "Required scope: project_templates:read\n\nReturns the compact project template records for all project templates in the team.", "tags": [ "Project templates" ], "operationId": "getProjectTemplatesForTeam", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "description", "html_description", "name", "offset", "owner", "path", "public", "requested_dates", "requested_dates.description", "requested_dates.name", "requested_roles", "requested_roles.name", "team", "team.name", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "description", "html_description", "name", "offset", "owner", "path", "public", "requested_dates", "requested_dates.description", "requested_dates.name", "requested_roles", "requested_roles.name", "team", "team.name", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested team's project templates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "project_templates:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.projecttemplates.getProjectTemplatesForTeam(teamGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectTemplatesApiInstance = new Asana.ProjectTemplatesApi();\nlet team_gid = \"159874\"; // String | Globally unique identifier for the team.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"color,description,html_description,name,offset,owner,path,public,requested_dates,requested_dates.description,requested_dates.name,requested_roles,requested_roles.name,team,team.name,uri\"\n};\nprojectTemplatesApiInstance.getProjectTemplatesForTeam(team_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projecttemplates.getProjectTemplatesForTeam(teamGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_templates_api_instance = asana.ProjectTemplatesApi(api_client)\nteam_gid = \"159874\" # str | Globally unique identifier for the team.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"color,description,html_description,name,offset,owner,path,public,requested_dates,requested_dates.description,requested_dates.name,requested_roles,requested_roles.name,team,team.name,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a team's project templates\n api_response = project_templates_api_instance.get_project_templates_for_team(team_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling ProjectTemplatesApi->get_project_templates_for_team: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_templates.get_project_templates_for_team(team_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projecttemplates->getProjectTemplatesForTeam($team_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_templates.get_project_templates_for_team(team_gid: 'team_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/project_templates/{project_template_gid}/instantiateProject": { "parameters": [ { "name": "project_template_gid", "in": "path", "description": "Globally unique identifier for the project template.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project_template" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Instantiate a project from a project template", "description": "Required scope: projects:write\n\nCreates and returns a job that will asynchronously handle the project instantiation.\n\nTo form this request, it is recommended to first make a request to [get a project template](/reference/getprojecttemplate). Then, from the response, copy the `gid` from the object in the `requested_dates` array. This `gid` should be used in `requested_dates` to instantiate a project.\n\n_Note: The body of this request will differ if your workspace is an organization. To determine if your workspace is an organization, use the [is_organization](/reference/workspaces) parameter._", "tags": [ "Project templates" ], "operationId": "instantiateProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "new_graph_export", "new_graph_export.completed_at", "new_graph_export.created_at", "new_graph_export.download_url", "new_project", "new_project.name", "new_project_template", "new_project_template.name", "new_resource_export", "new_resource_export.completed_at", "new_resource_export.created_at", "new_resource_export.download_url", "new_task", "new_task.created_by", "new_task.name", "new_task.resource_subtype", "new_task_template", "new_task_template.name", "resource_subtype", "status" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "new_graph_export", "new_graph_export.completed_at", "new_graph_export.created_at", "new_graph_export.download_url", "new_project", "new_project.name", "new_project_template", "new_project_template.name", "new_resource_export", "new_resource_export.completed_at", "new_resource_export.created_at", "new_resource_export.download_url", "new_task", "new_task.created_by", "new_task.name", "new_task.resource_subtype", "new_task_template", "new_task_template.name", "resource_subtype", "status" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Describes the inputs used for instantiating a project, such as the resulting project's name, which team it should be created in, and values for date variables.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "name" ], "properties": { "name": { "description": "The name of the new project.", "type": "string", "example": "New Project Name" }, "team": { "description": "*Optional*. Sets the team of the new project. If the project template exists in an _organization_, you may specify a value for `team`. If no value is provided then it defaults to the same team as the project template.", "type": "string", "example": "12345" }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "deprecated": true, "type": "boolean", "example": true }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "is_strict": { "description": "*Optional*. If set to `true`, the endpoint returns an \"Unprocessable Entity\" error if you fail to provide a calendar date value for any date variable. If set to `false`, a default date is used for each unfulfilled date variable (e.g., the current date is used as the Start Date of a project).", "type": "boolean", "example": true }, "requested_dates": { "description": "*Conditional*. Array of mappings of date variables to calendar dates. This property is required in the instantiation request if the project template includes dates (e.g., a start date on a task).", "type": "array", "items": { "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the date field in the project template. A value of `1` refers to the project start date, while `2` refers to the project due date.", "type": "string", "example": "1" }, "value": { "description": "The date with which the date variable should be replaced when instantiating a project. This takes a date with `YYYY-MM-DD` format.", "type": "string", "nullable": true, "format": "date-time", "example": "2022-01-01" } } } }, "requested_roles": { "description": "Array of mappings of template roles to user ids", "type": "array", "items": { "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the template role in the project template.", "type": "string", "example": "1" }, "value": { "description": "The user id that should be assigned to the template role.", "type": "string", "example": "123" } } } } } } } } } } }, "responses": { "201": { "description": "Successfully created the job to handle project instantiation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A *job* is an object representing a process that handles asynchronous work.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "job", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "duplicate_task" }, "status": { "description": "The current status of this job.", "type": "string", "enum": [ "not_started", "in_progress", "succeeded", "failed" ], "readOnly": true, "example": "in_progress" }, "new_project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "new_task": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "nullable": true } ] }, "new_project_template": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, "new_graph_export": { "description": "A *graph_export* object represents a request to export the data starting from a parent object", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "graph_export", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin JSON format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or\nfailed. If present, this URL may only be valid for 1 hour from\nthe time of retrieval. You should avoid persisting this URL\nsomewhere and rather refresh on demand to ensure you do not keep\nstale URLs.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/domain_export/7588024658887731/download/ domain_export_2563645399633793_7588024658887731_2023018-201726.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Content-Sha256=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host&x-id=GetObject#_=_" }, "completed_at": { "description": "The time at which this resource was completed.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } }, "new_resource_export": { "description": "A *resource_export* object represents a request to bulk export objects for one or more resources.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "export_request", "x-insert-after": "gid" }, "created_at": { "description": "The time at which the resource export object was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin [JSON Lines](https://jsonlines.org/) format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or failed.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/object_export/7588024658887731/download/ object_export_2563645399633793_7588024658887731_2023018-201726.jsonl.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Credential=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host" }, "completed_at": { "description": "The time at which this resource was completed. This will be null if the export is still in progress.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJob result = client.projecttemplates.instantiateProject(projectTemplateGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectTemplatesApiInstance = new Asana.ProjectTemplatesApi();\nlet project_template_gid = \"1331\"; // String | Globally unique identifier for the project template.\nlet opts = { \n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, \n 'opt_fields': \"new_graph_export,new_graph_export.completed_at,new_graph_export.created_at,new_graph_export.download_url,new_project,new_project.name,new_project_template,new_project_template.name,new_resource_export,new_resource_export.completed_at,new_resource_export.created_at,new_resource_export.download_url,new_task,new_task.created_by,new_task.name,new_task.resource_subtype,resource_subtype,status\"\n};\nprojectTemplatesApiInstance.instantiateProject(project_template_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projecttemplates.instantiateProject(projectTemplateGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nproject_templates_api_instance = asana.ProjectTemplatesApi(api_client)\nproject_template_gid = \"1331\" # str | Globally unique identifier for the project template.\nopts = {\n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, # dict | Describes the inputs used for instantiating a project, such as the resulting project's name, which team it should be created in, and values for date variables.\n 'opt_fields': \"new_graph_export,new_graph_export.completed_at,new_graph_export.created_at,new_graph_export.download_url,new_project,new_project.name,new_project_template,new_project_template.name,new_resource_export,new_resource_export.completed_at,new_resource_export.created_at,new_resource_export.download_url,new_task,new_task.created_by,new_task.name,new_task.resource_subtype,resource_subtype,status\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Instantiate a project from a project template\n api_response = project_templates_api_instance.instantiate_project(project_template_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectTemplatesApi->instantiate_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.project_templates.instantiate_project(project_template_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projecttemplates->instantiateProject($project_template_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.project_templates.instantiate_project(project_template_gid: 'project_template_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 9, "x-moar-complexity-skipped": false } }, "/projects": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get multiple projects", "description": "Required scope: projects:read\n\nReturns the compact project records for some filtered set of projects. Use one or more of the parameters provided to filter the projects returned.\n*Note: This endpoint may timeout for large domains. Try filtering by team!*", "tags": [ "Projects" ], "operationId": "getProjects", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "workspace", "in": "query", "description": "The workspace or organization to filter projects on.", "schema": { "type": "string" }, "example": "1331" }, { "name": "team", "in": "query", "description": "The team to filter projects on.", "schema": { "type": "string" }, "example": "14916" }, { "name": "archived", "in": "query", "description": "Only return projects whose `archived` field takes on the value of this parameter.", "schema": { "type": "boolean" }, "example": false }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "offset", "owner", "path", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "offset", "owner", "path", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved projects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.projects.getProjects(archived, team, workspace)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'workspace': \"1331\", \n 'team': \"14916\", \n 'archived': false, \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,offset,owner,path,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,uri,workspace,workspace.name\"\n};\nprojectsApiInstance.getProjects(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.getProjects({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'workspace': \"1331\", # str | The workspace or organization to filter projects on.\n 'team': \"14916\", # str | The team to filter projects on.\n 'archived': False, # bool | Only return projects whose `archived` field takes on the value of this parameter.\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,offset,owner,path,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple projects\n api_response = projects_api_instance.get_projects(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->get_projects: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.get_projects({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->getProjects(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.get_projects(param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a project", "description": "Required scope: projects:write\n\nCreate a new project in a workspace or team.\n\nEvery project is required to be created in a specific workspace or\norganization, and this cannot be changed once set. Note that you can use\nthe `workspace` parameter regardless of whether or not it is an\norganization.\n\nIf the workspace for your project is an organization, you must also\nsupply a `team` to share the project with.\n\nReturns the full record of the newly created project.", "tags": [ "Projects" ], "operationId": "createProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The project to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "An object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, or object (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.", "type": "object", "additionalProperties": { "type": "string", "description": "\"{custom_field_gid}\" => Value (can be text, a number, etc.). For date, use format \"YYYY-MM-DD\" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z)." }, "example": { "5678904321": "On Hold", "4578152156": "Not Started" } }, "followers": { "description": "*Create-only*. Comma separated string of users. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "string", "example": "12345,23456" }, "owner": { "description": "The current owner of the project, may be null.", "nullable": true, "type": "string", "example": "12345" }, "team": { "description": "The team that this project is shared with.", "type": "string", "example": "12345" }, "workspace": { "type": "string", "description": "The `gid` of a workspace.", "example": "12345" } } } ] } } } } } }, "responses": { "201": { "description": "Successfully retrieved projects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "Array of Custom Fields.", "readOnly": true, "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "completed": { "description": "True if the project is currently marked complete, false if not.", "type": "boolean", "readOnly": true, "example": false }, "completed_at": { "description": "The time at which this project was completed, or null if the project is not completed.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "description": "The user that marked this project complete, or null if the project is not completed.", "readOnly": true, "nullable": true } ] }, "followers": { "description": "Array of users following this project. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "owner": { "description": "The current owner of the project, may be null.", "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "description": "The team that this project is shared with." } ] }, "icon": { "description": "The icon for a project.", "type": "string", "nullable": true, "enum": [ "list", "board", "timeline", "calendar", "rocket", "people", "graph", "star", "bug", "light_bulb", "globe", "gear", "notebook", "computer", "check", "target", "html", "megaphone", "chat_bubbles", "briefcase", "page_layout", "mountain_flag", "puzzle", "presentation", "line_and_symbols", "speed_dial", "ribbon", "shoe", "shopping_basket", "map", "ticket", "coins" ], "example": "chat_bubbles" }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/project/123456789" }, "project_brief": { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project brief associated with this project.", "nullable": true } ] }, "created_from_template": { "allOf": [ { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project template from which this project was created. If the project was not created from a template, this field will be null.", "nullable": true } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace or organization this project is associated with. Once created, projects cannot be moved to a different workspace. This attribute can only be specified at creation time. If the workspace for your project is an organization, you must also supply a `team` in the request body." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nProject result = client.projects.createProject()\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The project to create.\nlet opts = { \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\"\n};\nprojectsApiInstance.createProject(body, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.createProject({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The project to create.\nopts = {\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a project\n api_response = projects_api_instance.create_project(body, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->create_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.create_project({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->createProject(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.create_project(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 112, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a project", "description": "Required scope: projects:read\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
FieldRequired Scope
custom_field_settingscustom_fields:read
teamteams:read
\n\nReturns the complete project record for a single project.", "tags": [ "Projects" ], "operationId": "getProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "Array of Custom Fields.", "readOnly": true, "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "completed": { "description": "True if the project is currently marked complete, false if not.", "type": "boolean", "readOnly": true, "example": false }, "completed_at": { "description": "The time at which this project was completed, or null if the project is not completed.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "description": "The user that marked this project complete, or null if the project is not completed.", "readOnly": true, "nullable": true } ] }, "followers": { "description": "Array of users following this project. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "owner": { "description": "The current owner of the project, may be null.", "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "description": "The team that this project is shared with." } ] }, "icon": { "description": "The icon for a project.", "type": "string", "nullable": true, "enum": [ "list", "board", "timeline", "calendar", "rocket", "people", "graph", "star", "bug", "light_bulb", "globe", "gear", "notebook", "computer", "check", "target", "html", "megaphone", "chat_bubbles", "briefcase", "page_layout", "mountain_flag", "puzzle", "presentation", "line_and_symbols", "speed_dial", "ribbon", "shoe", "shopping_basket", "map", "ticket", "coins" ], "example": "chat_bubbles" }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/project/123456789" }, "project_brief": { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project brief associated with this project.", "nullable": true } ] }, "created_from_template": { "allOf": [ { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project template from which this project was created. If the project was not created from a template, this field will be null.", "nullable": true } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace or organization this project is associated with. Once created, projects cannot be moved to a different workspace. This attribute can only be specified at creation time. If the workspace for your project is an organization, you must also supply a `team` in the request body." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nProject result = client.projects.getProject(projectGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\"\n};\nprojectsApiInstance.getProject(project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.getProject(projectGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a project\n api_response = projects_api_instance.get_project(project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->get_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.get_project(project_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->getProject($project_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.get_project(project_gid: 'project_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a project", "description": "Required scope: projects:write\n\nA specific, existing project can be updated by making a PUT request on\nthe URL for that project. Only the fields provided in the `data` block\nwill be updated; any unspecified fields will remain unchanged.\n\nWhen using this method, it is best to specify only those fields you wish\nto change, or else you may overwrite changes made by another user since\nyou last retrieved the task.\n\nReturns the complete updated project record.", "tags": [ "Projects" ], "operationId": "updateProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The updated fields for the project.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "An object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, or object (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.", "type": "object", "additionalProperties": { "type": "string", "description": "\"{custom_field_gid}\" => Value (can be text, a number, etc.). For date, use format \"YYYY-MM-DD\" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z)." }, "example": { "5678904321": "On Hold", "4578152156": "Not Started" } }, "followers": { "description": "*Create-only*. Comma separated string of users. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "string", "example": "12345,23456" }, "owner": { "description": "The current owner of the project, may be null.", "nullable": true, "type": "string", "example": "12345" }, "team": { "description": "The team that this project is shared with.", "type": "string", "example": "12345" } } } ] } } } } } }, "responses": { "200": { "description": "Successfully updated the project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "Array of Custom Fields.", "readOnly": true, "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "completed": { "description": "True if the project is currently marked complete, false if not.", "type": "boolean", "readOnly": true, "example": false }, "completed_at": { "description": "The time at which this project was completed, or null if the project is not completed.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "description": "The user that marked this project complete, or null if the project is not completed.", "readOnly": true, "nullable": true } ] }, "followers": { "description": "Array of users following this project. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "owner": { "description": "The current owner of the project, may be null.", "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "description": "The team that this project is shared with." } ] }, "icon": { "description": "The icon for a project.", "type": "string", "nullable": true, "enum": [ "list", "board", "timeline", "calendar", "rocket", "people", "graph", "star", "bug", "light_bulb", "globe", "gear", "notebook", "computer", "check", "target", "html", "megaphone", "chat_bubbles", "briefcase", "page_layout", "mountain_flag", "puzzle", "presentation", "line_and_symbols", "speed_dial", "ribbon", "shoe", "shopping_basket", "map", "ticket", "coins" ], "example": "chat_bubbles" }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/project/123456789" }, "project_brief": { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project brief associated with this project.", "nullable": true } ] }, "created_from_template": { "allOf": [ { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project template from which this project was created. If the project was not created from a template, this field will be null.", "nullable": true } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace or organization this project is associated with. Once created, projects cannot be moved to a different workspace. This attribute can only be specified at creation time. If the workspace for your project is an organization, you must also supply a `team` in the request body." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nProject result = client.projects.updateProject(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The updated fields for the project.\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\"\n};\nprojectsApiInstance.updateProject(body, project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.updateProject(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The updated fields for the project.\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a project\n api_response = projects_api_instance.update_project(body, project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->update_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.update_project(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->updateProject($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.update_project(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 111, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a project", "description": "Required scope: projects:delete\n\nA specific, existing project can be deleted by making a DELETE request on\nthe URL for that project.\n\nReturns an empty data record.", "tags": [ "Projects" ], "operationId": "deleteProject", "responses": { "200": { "description": "Successfully deleted the specified project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:delete" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.projects.deleteProject(projectGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\n\nprojectsApiInstance.deleteProject(project_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.deleteProject(projectGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\n\n\ntry:\n # Delete a project\n api_response = projects_api_instance.delete_project(project_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->delete_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.delete_project(project_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->deleteProject($project_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.delete_project(project_gid: 'project_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/duplicate": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Duplicate a project", "description": "Required scope: projects:write\n\nCreates and returns a job that will asynchronously handle the duplication.", "tags": [ "Projects" ], "operationId": "duplicateProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "new_graph_export", "new_graph_export.completed_at", "new_graph_export.created_at", "new_graph_export.download_url", "new_project", "new_project.name", "new_project_template", "new_project_template.name", "new_resource_export", "new_resource_export.completed_at", "new_resource_export.created_at", "new_resource_export.download_url", "new_task", "new_task.created_by", "new_task.name", "new_task.resource_subtype", "new_task_template", "new_task_template.name", "resource_subtype", "status" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "new_graph_export", "new_graph_export.completed_at", "new_graph_export.created_at", "new_graph_export.download_url", "new_project", "new_project.name", "new_project_template", "new_project_template.name", "new_resource_export", "new_resource_export.completed_at", "new_resource_export.created_at", "new_resource_export.download_url", "new_task", "new_task.created_by", "new_task.name", "new_task.resource_subtype", "new_task_template", "new_task_template.name", "resource_subtype", "status" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Describes the duplicate's name and the elements that will be duplicated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "name" ], "properties": { "name": { "description": "The name of the new project.", "type": "string", "example": "New Project Name" }, "team": { "description": "Sets the team of the new project. If team is not defined, the new project will be in the same team as the the original project.", "type": "string", "example": "12345" }, "include": { "description": "A comma-separated list of elements to include when duplicating a project.\nSome elements are automatically included and cannot be excluded,\nwhile others are **optional** and must be explicitly specified in this field.\n\n**Auto-included fields (non-configurable)**\n- Tasks\n- [Project Views](https://asana.com/features/project-management/project-views)\n(i.e., tabs in a project such as List, Board, Dashboard, etc.)\n- [Rules](https://help.asana.com/s/article/rules)\n\n*Note: The Owner of the Rules copied to the new project is the user who performs the API call.\nIf the duplication is performed using a [Service Account](/docs/authentication#/service-account),\nnote that Service Accounts cannot access the UI to modify or pause Rules.\nTo prevent unwanted automation behavior, consider pausing Rules in the source project before duplication \u2014\ntheir active/paused state is preserved in the new project.*\n\n**Optional fields (configurable)**\n- allocations\n- forms\n- members\n- notes\n- permissions\n- task_assignee\n- task_attachments\n- task_dates\n- task_dependencies\n- task_followers\n- task_notes\n- task_projects\n- task_subtasks\n- task_tags\n- task_templates\n- task_type_default", "type": "string", "pattern": "([allocations|forms|members|notes|permissions|task_assignee|task_attachments|task_dates|task_dependencies|task_followers|task_notes|task_projects|task_subtasks|task_tags|task_templates|task_type_default])(,\\1)*", "example": [ "allocations,forms,members,notes,permissions,task_assignee,task_attachments,task_dates,task_dependencies,task_followers,task_notes,task_projects,task_subtasks,task_tags,task_templates,task_type_default" ] }, "schedule_dates": { "description": "A dictionary of options to auto-shift dates. `task_dates` must be included to use this option. Requires `should_skip_weekends` and either `start_on` or `due_on`, but not both.", "type": "object", "properties": { "should_skip_weekends": { "description": "**Required**: Determines if the auto-shifted dates should skip weekends.", "type": "boolean", "example": true }, "due_on": { "description": "Sets the last due date in the duplicated project to the given date. The rest of the due dates will be offset by the same amount as the due dates in the original project.", "type": "string", "example": "2019-05-21" }, "start_on": { "description": "Sets the first start date in the duplicated project to the given date. The rest of the start dates will be offset by the same amount as the start dates in the original project.", "type": "string", "example": "2019-05-21" } } } } } } } } } }, "responses": { "201": { "description": "Successfully created the job to handle duplication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A *job* is an object representing a process that handles asynchronous work.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "job", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "duplicate_task" }, "status": { "description": "The current status of this job.", "type": "string", "enum": [ "not_started", "in_progress", "succeeded", "failed" ], "readOnly": true, "example": "in_progress" }, "new_project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "new_task": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "nullable": true } ] }, "new_project_template": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, "new_graph_export": { "description": "A *graph_export* object represents a request to export the data starting from a parent object", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "graph_export", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin JSON format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or\nfailed. If present, this URL may only be valid for 1 hour from\nthe time of retrieval. You should avoid persisting this URL\nsomewhere and rather refresh on demand to ensure you do not keep\nstale URLs.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/domain_export/7588024658887731/download/ domain_export_2563645399633793_7588024658887731_2023018-201726.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Content-Sha256=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host&x-id=GetObject#_=_" }, "completed_at": { "description": "The time at which this resource was completed.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } }, "new_resource_export": { "description": "A *resource_export* object represents a request to bulk export objects for one or more resources.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "export_request", "x-insert-after": "gid" }, "created_at": { "description": "The time at which the resource export object was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin [JSON Lines](https://jsonlines.org/) format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or failed.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/object_export/7588024658887731/download/ object_export_2563645399633793_7588024658887731_2023018-201726.jsonl.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Credential=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host" }, "completed_at": { "description": "The time at which this resource was completed. This will be null if the export is still in progress.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJob result = client.projects.duplicateProject(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, \n 'opt_fields': \"new_graph_export,new_graph_export.completed_at,new_graph_export.created_at,new_graph_export.download_url,new_project,new_project.name,new_project_template,new_project_template.name,new_resource_export,new_resource_export.completed_at,new_resource_export.created_at,new_resource_export.download_url,new_task,new_task.created_by,new_task.name,new_task.resource_subtype,resource_subtype,status\"\n};\nprojectsApiInstance.duplicateProject(project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.duplicateProject(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, # dict | Describes the duplicate's name and the elements that will be duplicated.\n 'opt_fields': \"new_graph_export,new_graph_export.completed_at,new_graph_export.created_at,new_graph_export.download_url,new_project,new_project.name,new_project_template,new_project_template.name,new_resource_export,new_resource_export.completed_at,new_resource_export.created_at,new_resource_export.download_url,new_task,new_task.created_by,new_task.name,new_task.resource_subtype,resource_subtype,status\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Duplicate a project\n api_response = projects_api_instance.duplicate_project(project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->duplicate_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.duplicate_project(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->duplicateProject($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.duplicate_project(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 6, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/projects": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get projects a task is in", "description": "Required scope: projects:read\n\nReturns a compact representation of all of the projects the task is in.", "tags": [ "Projects" ], "operationId": "getProjectsForTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "offset", "owner", "path", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "offset", "owner", "path", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the projects for the given task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.projects.getProjectsForTask(taskGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,offset,owner,path,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,uri,workspace,workspace.name\"\n};\nprojectsApiInstance.getProjectsForTask(task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.getProjectsForTask(taskGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,offset,owner,path,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get projects a task is in\n api_response = projects_api_instance.get_projects_for_task(task_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->get_projects_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.get_projects_for_task(task_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->getProjectsForTask($task_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.get_projects_for_task(task_gid: 'task_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/teams/{team_gid}/projects": { "parameters": [ { "name": "team_gid", "in": "path", "description": "Globally unique identifier for the team.", "required": true, "schema": { "type": "string" }, "example": "159874", "x-env-variable": "team" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a team's projects", "description": "Required scope: projects:read\n\nReturns the compact project records for all projects in the team.", "tags": [ "Projects" ], "operationId": "getProjectsForTeam", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "description": "Only return projects whose `archived` field takes on the value of this parameter.", "schema": { "type": "boolean" }, "example": false }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "offset", "owner", "path", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "offset", "owner", "path", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested team's projects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.projects.getProjectsForTeam(teamGid, archived)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet team_gid = \"159874\"; // String | Globally unique identifier for the team.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'archived': false, \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,offset,owner,path,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,uri,workspace,workspace.name\"\n};\nprojectsApiInstance.getProjectsForTeam(team_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.getProjectsForTeam(teamGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nteam_gid = \"159874\" # str | Globally unique identifier for the team.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'archived': False, # bool | Only return projects whose `archived` field takes on the value of this parameter.\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,offset,owner,path,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a team's projects\n api_response = projects_api_instance.get_projects_for_team(team_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->get_projects_for_team: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.get_projects_for_team(team_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->getProjectsForTeam($team_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.get_projects_for_team(team_gid: 'team_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a project in a team", "description": "Required scope: projects:write\n\nCreates a project shared with the given team.\n\nReturns the full record of the newly created project.", "tags": [ "Projects" ], "operationId": "createProjectForTeam", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The new project to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "An object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, or object (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.", "type": "object", "additionalProperties": { "type": "string", "description": "\"{custom_field_gid}\" => Value (can be text, a number, etc.). For date, use format \"YYYY-MM-DD\" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z)." }, "example": { "5678904321": "On Hold", "4578152156": "Not Started" } }, "followers": { "description": "*Create-only*. Comma separated string of users. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "string", "example": "12345,23456" }, "owner": { "description": "The current owner of the project, may be null.", "nullable": true, "type": "string", "example": "12345" }, "team": { "description": "The team that this project is shared with.", "type": "string", "example": "12345" }, "workspace": { "type": "string", "description": "The `gid` of a workspace.", "example": "12345" } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created the specified project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "Array of Custom Fields.", "readOnly": true, "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "completed": { "description": "True if the project is currently marked complete, false if not.", "type": "boolean", "readOnly": true, "example": false }, "completed_at": { "description": "The time at which this project was completed, or null if the project is not completed.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "description": "The user that marked this project complete, or null if the project is not completed.", "readOnly": true, "nullable": true } ] }, "followers": { "description": "Array of users following this project. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "owner": { "description": "The current owner of the project, may be null.", "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "description": "The team that this project is shared with." } ] }, "icon": { "description": "The icon for a project.", "type": "string", "nullable": true, "enum": [ "list", "board", "timeline", "calendar", "rocket", "people", "graph", "star", "bug", "light_bulb", "globe", "gear", "notebook", "computer", "check", "target", "html", "megaphone", "chat_bubbles", "briefcase", "page_layout", "mountain_flag", "puzzle", "presentation", "line_and_symbols", "speed_dial", "ribbon", "shoe", "shopping_basket", "map", "ticket", "coins" ], "example": "chat_bubbles" }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/project/123456789" }, "project_brief": { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project brief associated with this project.", "nullable": true } ] }, "created_from_template": { "allOf": [ { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project template from which this project was created. If the project was not created from a template, this field will be null.", "nullable": true } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace or organization this project is associated with. Once created, projects cannot be moved to a different workspace. This attribute can only be specified at creation time. If the workspace for your project is an organization, you must also supply a `team` in the request body." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nProject result = client.projects.createProjectForTeam(teamGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The new project to create.\nlet team_gid = \"159874\"; // String | Globally unique identifier for the team.\nlet opts = { \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\"\n};\nprojectsApiInstance.createProjectForTeam(body, team_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.createProjectForTeam(teamGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The new project to create.\nteam_gid = \"159874\" # str | Globally unique identifier for the team.\nopts = {\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a project in a team\n api_response = projects_api_instance.create_project_for_team(body, team_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->create_project_for_team: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.create_project_for_team(team_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->createProjectForTeam($team_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.create_project_for_team(team_gid: 'team_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 112, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/projects": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get all projects in a workspace", "description": "Required scope: projects:read\n\nReturns the compact project records for all projects in the workspace.\n*Note: This endpoint may timeout for large domains. Prefer the `/teams/{team_gid}/projects` endpoint.*", "tags": [ "Projects" ], "operationId": "getProjectsForWorkspace", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "description": "Only return projects whose `archived` field takes on the value of this parameter.", "schema": { "type": "boolean" }, "example": false }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "offset", "owner", "path", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "offset", "owner", "path", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested workspace's projects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.projects.getProjectsForWorkspace(workspaceGid, archived)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'archived': false, \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,offset,owner,path,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,uri,workspace,workspace.name\"\n};\nprojectsApiInstance.getProjectsForWorkspace(workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.getProjectsForWorkspace(workspaceGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'archived': False, # bool | Only return projects whose `archived` field takes on the value of this parameter.\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,offset,owner,path,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get all projects in a workspace\n api_response = projects_api_instance.get_projects_for_workspace(workspace_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->get_projects_for_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.get_projects_for_workspace(workspace_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->getProjectsForWorkspace($workspace_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.get_projects_for_workspace(workspace_gid: 'workspace_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a project in a workspace", "description": "Required scope: projects:write\n\nCreates a project in the workspace.\n\nIf the workspace for your project is an organization, you must also\nsupply a team to share the project with.\n\nReturns the full record of the newly created project.", "tags": [ "Projects" ], "operationId": "createProjectForWorkspace", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The new project to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "An object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, or object (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.", "type": "object", "additionalProperties": { "type": "string", "description": "\"{custom_field_gid}\" => Value (can be text, a number, etc.). For date, use format \"YYYY-MM-DD\" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z)." }, "example": { "5678904321": "On Hold", "4578152156": "Not Started" } }, "followers": { "description": "*Create-only*. Comma separated string of users. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "string", "example": "12345,23456" }, "owner": { "description": "The current owner of the project, may be null.", "nullable": true, "type": "string", "example": "12345" }, "team": { "description": "The team that this project is shared with.", "type": "string", "example": "12345" }, "workspace": { "type": "string", "description": "The `gid` of a workspace.", "example": "12345" } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created a new project in the specified workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "Array of Custom Fields.", "readOnly": true, "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "completed": { "description": "True if the project is currently marked complete, false if not.", "type": "boolean", "readOnly": true, "example": false }, "completed_at": { "description": "The time at which this project was completed, or null if the project is not completed.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "description": "The user that marked this project complete, or null if the project is not completed.", "readOnly": true, "nullable": true } ] }, "followers": { "description": "Array of users following this project. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "owner": { "description": "The current owner of the project, may be null.", "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "description": "The team that this project is shared with." } ] }, "icon": { "description": "The icon for a project.", "type": "string", "nullable": true, "enum": [ "list", "board", "timeline", "calendar", "rocket", "people", "graph", "star", "bug", "light_bulb", "globe", "gear", "notebook", "computer", "check", "target", "html", "megaphone", "chat_bubbles", "briefcase", "page_layout", "mountain_flag", "puzzle", "presentation", "line_and_symbols", "speed_dial", "ribbon", "shoe", "shopping_basket", "map", "ticket", "coins" ], "example": "chat_bubbles" }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/project/123456789" }, "project_brief": { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project brief associated with this project.", "nullable": true } ] }, "created_from_template": { "allOf": [ { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project template from which this project was created. If the project was not created from a template, this field will be null.", "nullable": true } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace or organization this project is associated with. Once created, projects cannot be moved to a different workspace. This attribute can only be specified at creation time. If the workspace for your project is an organization, you must also supply a `team` in the request body." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nProject result = client.projects.createProjectForWorkspace(workspaceGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The new project to create.\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\"\n};\nprojectsApiInstance.createProjectForWorkspace(body, workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.createProjectForWorkspace(workspaceGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The new project to create.\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a project in a workspace\n api_response = projects_api_instance.create_project_for_workspace(body, workspace_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->create_project_for_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.create_project_for_workspace(workspace_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->createProjectForWorkspace($workspace_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.create_project_for_workspace(workspace_gid: 'workspace_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 112, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/addCustomFieldSetting": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add a custom field to a project", "description": "Required scope: projects:write\n\nCustom fields are associated with projects by way of custom field settings. This method creates a setting for the project.", "tags": [ "Projects" ], "operationId": "addCustomFieldSettingForProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "custom_field", "custom_field.asana_created_field", "custom_field.created_by", "custom_field.created_by.name", "custom_field.currency_code", "custom_field.custom_label", "custom_field.custom_label_position", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.default_access_level", "custom_field.description", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.format", "custom_field.has_notifications_enabled", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.is_global_to_workspace", "custom_field.is_value_read_only", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.people_value", "custom_field.people_value.name", "custom_field.precision", "custom_field.privacy_setting", "custom_field.reference_value", "custom_field.reference_value.name", "custom_field.representation_type", "custom_field.resource_subtype", "custom_field.text_value", "custom_field.type", "is_important", "parent", "parent.name", "project", "project.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "custom_field", "custom_field.asana_created_field", "custom_field.created_by", "custom_field.created_by.name", "custom_field.currency_code", "custom_field.custom_label", "custom_field.custom_label_position", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.default_access_level", "custom_field.description", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.format", "custom_field.has_notifications_enabled", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.is_global_to_workspace", "custom_field.is_value_read_only", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.people_value", "custom_field.people_value.name", "custom_field.precision", "custom_field.privacy_setting", "custom_field.reference_value", "custom_field.reference_value.name", "custom_field.representation_type", "custom_field.resource_subtype", "custom_field.text_value", "custom_field.type", "is_important", "parent", "parent.name", "project", "project.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Information about the custom field setting.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "custom_field" ], "properties": { "custom_field": { "oneOf": [ { "type": "string", "description": "The custom field to associate with this container.", "example": "14916" }, { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "required": [ "workspace" ], "properties": { "workspace": { "type": "string", "description": "*Create-Only* The workspace to create a custom field in.", "example": "1331" }, "owned_by_app": { "type": "boolean", "description": "*Allow-listed*. Instructs the API that this Custom Field is app-owned. This parameter is allow-listed to specific apps at this point in time. For apps that are not allow-listed, providing this parameter will result in a `403 Forbidden`." }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of user GIDs reflects the users to be written to a `people` custom field. Note that *write* operations will replace existing users (if any) in the custom field with the users specified in this array.", "type": "array", "items": { "type": "string", "description": "The GID of a user." }, "example": [ "12345" ] }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of GIDs reflects the objects to be written to a `reference` custom field. Note that *write* operations will replace existing objects (if any) in the custom field with the objects specified in this array.", "type": "array", "items": { "type": "string", "description": "The GID of an object." }, "example": [ "12345" ] } } } ] }, { "type": "object", "required": [ "resource_subtype" ], "properties": { "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.", "type": "string", "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] } ] }, "is_important": { "description": "Whether this field should be considered important to this container (for instance, to display in the list view of items in the container).", "type": "boolean", "example": true }, "insert_before": { "description": "A gid of a Custom Field Setting on this container, before which the new Custom Field Setting will be added. `insert_before` and `insert_after` parameters cannot both be specified.", "type": "string", "example": "1331" }, "insert_after": { "description": "A gid of a Custom Field Setting on this container, after which the new Custom Field Setting will be added. `insert_before` and `insert_after` parameters cannot both be specified.", "type": "string", "example": "1331" } } } } } } } }, "responses": { "200": { "description": "Successfully added the custom field to the project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nCustomFieldSetting result = client.projects.addCustomFieldSettingForProject(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the custom field setting.\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'opt_fields': \"custom_field,custom_field.asana_created_field,custom_field.created_by,custom_field.created_by.name,custom_field.currency_code,custom_field.custom_label,custom_field.custom_label_position,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.default_access_level,custom_field.description,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.format,custom_field.has_notifications_enabled,custom_field.id_prefix,custom_field.is_formula_field,custom_field.is_global_to_workspace,custom_field.is_value_read_only,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.people_value,custom_field.people_value.name,custom_field.precision,custom_field.privacy_setting,custom_field.representation_type,custom_field.resource_subtype,custom_field.text_value,custom_field.type,is_important,parent,parent.name,project,project.name\"\n};\nprojectsApiInstance.addCustomFieldSettingForProject(body, project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.addCustomFieldSettingForProject(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the custom field setting.\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'opt_fields': \"custom_field,custom_field.asana_created_field,custom_field.created_by,custom_field.created_by.name,custom_field.currency_code,custom_field.custom_label,custom_field.custom_label_position,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.default_access_level,custom_field.description,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.format,custom_field.has_notifications_enabled,custom_field.id_prefix,custom_field.input_restrictions,custom_field.is_formula_field,custom_field.is_global_to_workspace,custom_field.is_value_read_only,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.people_value,custom_field.people_value.name,custom_field.precision,custom_field.privacy_setting,custom_field.reference_value,custom_field.reference_value.name,custom_field.representation_type,custom_field.resource_subtype,custom_field.text_value,custom_field.type,is_important,parent,parent.name,project,project.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Add a custom field to a project\n api_response = projects_api_instance.add_custom_field_setting_for_project(body, project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->add_custom_field_setting_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.add_custom_field_setting_for_project(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->addCustomFieldSettingForProject($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.add_custom_field_setting_for_project(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 52, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/removeCustomFieldSetting": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Remove a custom field from a project", "description": "Required scope: projects:write\n\nRemoves a custom field setting from a project.", "tags": [ "Projects" ], "operationId": "removeCustomFieldSettingForProject", "security": [ { "oauth2": [ "projects:write" ] } ], "requestBody": { "description": "Information about the custom field setting being removed.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "custom_field" ], "properties": { "custom_field": { "description": "The custom field to remove from this portfolio.", "type": "string", "example": "14916" } } } } } } } }, "responses": { "200": { "description": "Successfully removed the custom field from the project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.projects.removeCustomFieldSettingForProject(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the custom field setting being removed.\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\n\nprojectsApiInstance.removeCustomFieldSettingForProject(body, project_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.removeCustomFieldSettingForProject(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the custom field setting being removed.\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\n\n\ntry:\n # Remove a custom field from a project\n api_response = projects_api_instance.remove_custom_field_setting_for_project(body, project_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->remove_custom_field_setting_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.remove_custom_field_setting_for_project(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->removeCustomFieldSettingForProject($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.remove_custom_field_setting_for_project(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/task_counts": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get task count of a project", "description": "Required scope: projects:read\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
FieldRequired Scope
custom_field_settingscustom_fields:read
teamteams:read
\n\nGet an object that holds task count fields. **All fields are excluded by default**. You must [opt in](/docs/inputoutput-options) using `opt_fields` to get any information from this endpoint.\n\nThis endpoint has an additional [rate limit](/docs/rate-limits) and each field counts especially high against our [cost limits](/docs/rate-limits#cost-limits).\n\nMilestones are just tasks, so they are included in the `num_tasks`, `num_incomplete_tasks`, and `num_completed_tasks` counts.", "tags": [ "Projects" ], "operationId": "getTaskCountsForProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "num_completed_milestones", "num_completed_tasks", "num_incomplete_milestones", "num_incomplete_tasks", "num_milestones", "num_tasks" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "num_completed_milestones", "num_completed_tasks", "num_incomplete_milestones", "num_incomplete_tasks", "num_milestones", "num_tasks" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested project's task counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A response object returned from the task count endpoint.", "type": "object", "properties": { "num_tasks": { "description": "The number of tasks in a project.", "type": "integer", "example": 200 }, "num_incomplete_tasks": { "description": "The number of incomplete tasks in a project.", "type": "integer", "example": 50 }, "num_completed_tasks": { "description": "The number of completed tasks in a project.", "type": "integer", "example": 150 }, "num_milestones": { "description": "The number of milestones in a project.", "type": "integer", "example": 10 }, "num_incomplete_milestones": { "description": "The number of incomplete milestones in a project.", "type": "integer", "example": 7 }, "num_completed_milestones": { "description": "The number of completed milestones in a project.", "type": "integer", "example": 3 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "projects:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.projects.getTaskCountsForProject(projectGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'opt_fields': \"num_completed_milestones,num_completed_tasks,num_incomplete_milestones,num_incomplete_tasks,num_milestones,num_tasks\"\n};\nprojectsApiInstance.getTaskCountsForProject(project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.getTaskCountsForProject(projectGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'opt_fields': \"num_completed_milestones,num_completed_tasks,num_incomplete_milestones,num_incomplete_tasks,num_milestones,num_tasks\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get task count of a project\n api_response = projects_api_instance.get_task_counts_for_project(project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->get_task_counts_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.get_task_counts_for_project(project_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->getTaskCountsForProject($project_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.get_task_counts_for_project(project_gid: 'project_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/addMembers": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add users to a project", "description": "Adds the specified list of users as members of the project. Note that a user being added as a member may also be added as a *follower* as a result of this operation. This is because the user's default notification settings (i.e., in the \"Notifications\" tab of \"My Profile Settings\") will override this endpoint's default behavior of setting \"Tasks added\" notifications to `false`.\nReturns the updated project record.", "tags": [ "Projects" ], "operationId": "addMembersForProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Information about the members being added.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "members" ], "properties": { "members": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "521621,621373" } } } } } } } }, "responses": { "200": { "description": "Successfully added members to the project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "Array of Custom Fields.", "readOnly": true, "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "completed": { "description": "True if the project is currently marked complete, false if not.", "type": "boolean", "readOnly": true, "example": false }, "completed_at": { "description": "The time at which this project was completed, or null if the project is not completed.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "description": "The user that marked this project complete, or null if the project is not completed.", "readOnly": true, "nullable": true } ] }, "followers": { "description": "Array of users following this project. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "owner": { "description": "The current owner of the project, may be null.", "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "description": "The team that this project is shared with." } ] }, "icon": { "description": "The icon for a project.", "type": "string", "nullable": true, "enum": [ "list", "board", "timeline", "calendar", "rocket", "people", "graph", "star", "bug", "light_bulb", "globe", "gear", "notebook", "computer", "check", "target", "html", "megaphone", "chat_bubbles", "briefcase", "page_layout", "mountain_flag", "puzzle", "presentation", "line_and_symbols", "speed_dial", "ribbon", "shoe", "shopping_basket", "map", "ticket", "coins" ], "example": "chat_bubbles" }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/project/123456789" }, "project_brief": { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project brief associated with this project.", "nullable": true } ] }, "created_from_template": { "allOf": [ { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project template from which this project was created. If the project was not created from a template, this field will be null.", "nullable": true } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace or organization this project is associated with. Once created, projects cannot be moved to a different workspace. This attribute can only be specified at creation time. If the workspace for your project is an organization, you must also supply a `team` in the request body." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nProject result = client.projects.addMembersForProject(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the members being added.\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\"\n};\nprojectsApiInstance.addMembersForProject(body, project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.addMembersForProject(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the members being added.\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Add users to a project\n api_response = projects_api_instance.add_members_for_project(body, project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->add_members_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.add_members_for_project(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->addMembersForProject($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.add_members_for_project(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/removeMembers": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Remove users from a project", "description": "Removes the specified list of users from members of the project.\nReturns the updated project record.", "tags": [ "Projects" ], "operationId": "removeMembersForProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Information about the members being removed.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "members" ], "properties": { "members": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "521621,621373" } } } } } } } }, "responses": { "200": { "description": "Successfully removed the members from the project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "Array of Custom Fields.", "readOnly": true, "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "completed": { "description": "True if the project is currently marked complete, false if not.", "type": "boolean", "readOnly": true, "example": false }, "completed_at": { "description": "The time at which this project was completed, or null if the project is not completed.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "description": "The user that marked this project complete, or null if the project is not completed.", "readOnly": true, "nullable": true } ] }, "followers": { "description": "Array of users following this project. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "owner": { "description": "The current owner of the project, may be null.", "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "description": "The team that this project is shared with." } ] }, "icon": { "description": "The icon for a project.", "type": "string", "nullable": true, "enum": [ "list", "board", "timeline", "calendar", "rocket", "people", "graph", "star", "bug", "light_bulb", "globe", "gear", "notebook", "computer", "check", "target", "html", "megaphone", "chat_bubbles", "briefcase", "page_layout", "mountain_flag", "puzzle", "presentation", "line_and_symbols", "speed_dial", "ribbon", "shoe", "shopping_basket", "map", "ticket", "coins" ], "example": "chat_bubbles" }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/project/123456789" }, "project_brief": { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project brief associated with this project.", "nullable": true } ] }, "created_from_template": { "allOf": [ { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project template from which this project was created. If the project was not created from a template, this field will be null.", "nullable": true } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace or organization this project is associated with. Once created, projects cannot be moved to a different workspace. This attribute can only be specified at creation time. If the workspace for your project is an organization, you must also supply a `team` in the request body." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nProject result = client.projects.removeMembersForProject(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the members being removed.\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\"\n};\nprojectsApiInstance.removeMembersForProject(body, project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.removeMembersForProject(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the members being removed.\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Remove users from a project\n api_response = projects_api_instance.remove_members_for_project(body, project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->remove_members_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.remove_members_for_project(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->removeMembersForProject($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.remove_members_for_project(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/addFollowers": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add followers to a project", "description": "Adds the specified list of users as followers to the project. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project. Therefore, if the users are not already members of the project, they will also become members as a result of this operation.\nReturns the updated project record.", "tags": [ "Projects" ], "operationId": "addFollowersForProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Information about the followers being added.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "followers" ], "properties": { "followers": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "521621,621373" } } } } } } } }, "responses": { "200": { "description": "Successfully added followers to the project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "Array of Custom Fields.", "readOnly": true, "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "completed": { "description": "True if the project is currently marked complete, false if not.", "type": "boolean", "readOnly": true, "example": false }, "completed_at": { "description": "The time at which this project was completed, or null if the project is not completed.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "description": "The user that marked this project complete, or null if the project is not completed.", "readOnly": true, "nullable": true } ] }, "followers": { "description": "Array of users following this project. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "owner": { "description": "The current owner of the project, may be null.", "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "description": "The team that this project is shared with." } ] }, "icon": { "description": "The icon for a project.", "type": "string", "nullable": true, "enum": [ "list", "board", "timeline", "calendar", "rocket", "people", "graph", "star", "bug", "light_bulb", "globe", "gear", "notebook", "computer", "check", "target", "html", "megaphone", "chat_bubbles", "briefcase", "page_layout", "mountain_flag", "puzzle", "presentation", "line_and_symbols", "speed_dial", "ribbon", "shoe", "shopping_basket", "map", "ticket", "coins" ], "example": "chat_bubbles" }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/project/123456789" }, "project_brief": { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project brief associated with this project.", "nullable": true } ] }, "created_from_template": { "allOf": [ { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project template from which this project was created. If the project was not created from a template, this field will be null.", "nullable": true } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace or organization this project is associated with. Once created, projects cannot be moved to a different workspace. This attribute can only be specified at creation time. If the workspace for your project is an organization, you must also supply a `team` in the request body." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nProject result = client.projects.addFollowersForProject(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the followers being added.\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\"\n};\nprojectsApiInstance.addFollowersForProject(body, project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.addFollowersForProject(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the followers being added.\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Add followers to a project\n api_response = projects_api_instance.add_followers_for_project(body, project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->add_followers_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.add_followers_for_project(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->addFollowersForProject($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.add_followers_for_project(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/removeFollowers": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Remove followers from a project", "description": "Removes the specified list of users from following the project, this will not affect project membership status.\nReturns the updated project record.", "tags": [ "Projects" ], "operationId": "removeFollowersForProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "color", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_from_template", "created_from_template.name", "current_status", "current_status.author", "current_status.author.name", "current_status.color", "current_status.created_at", "current_status.created_by", "current_status.created_by.name", "current_status.html_text", "current_status.modified_at", "current_status.text", "current_status.title", "current_status_update", "current_status_update.resource_subtype", "current_status_update.title", "custom_field_settings", "custom_field_settings.custom_field", "custom_field_settings.custom_field.asana_created_field", "custom_field_settings.custom_field.created_by", "custom_field_settings.custom_field.created_by.name", "custom_field_settings.custom_field.currency_code", "custom_field_settings.custom_field.custom_label", "custom_field_settings.custom_field.custom_label_position", "custom_field_settings.custom_field.date_value", "custom_field_settings.custom_field.date_value.date", "custom_field_settings.custom_field.date_value.date_time", "custom_field_settings.custom_field.default_access_level", "custom_field_settings.custom_field.description", "custom_field_settings.custom_field.display_value", "custom_field_settings.custom_field.enabled", "custom_field_settings.custom_field.enum_options", "custom_field_settings.custom_field.enum_options.color", "custom_field_settings.custom_field.enum_options.enabled", "custom_field_settings.custom_field.enum_options.name", "custom_field_settings.custom_field.enum_value", "custom_field_settings.custom_field.enum_value.color", "custom_field_settings.custom_field.enum_value.enabled", "custom_field_settings.custom_field.enum_value.name", "custom_field_settings.custom_field.format", "custom_field_settings.custom_field.has_notifications_enabled", "custom_field_settings.custom_field.id_prefix", "custom_field_settings.custom_field.input_restrictions", "custom_field_settings.custom_field.is_formula_field", "custom_field_settings.custom_field.is_global_to_workspace", "custom_field_settings.custom_field.is_value_read_only", "custom_field_settings.custom_field.multi_enum_values", "custom_field_settings.custom_field.multi_enum_values.color", "custom_field_settings.custom_field.multi_enum_values.enabled", "custom_field_settings.custom_field.multi_enum_values.name", "custom_field_settings.custom_field.name", "custom_field_settings.custom_field.number_value", "custom_field_settings.custom_field.people_value", "custom_field_settings.custom_field.people_value.name", "custom_field_settings.custom_field.precision", "custom_field_settings.custom_field.privacy_setting", "custom_field_settings.custom_field.reference_value", "custom_field_settings.custom_field.reference_value.name", "custom_field_settings.custom_field.representation_type", "custom_field_settings.custom_field.resource_subtype", "custom_field_settings.custom_field.text_value", "custom_field_settings.custom_field.type", "custom_field_settings.is_important", "custom_field_settings.parent", "custom_field_settings.parent.name", "custom_field_settings.project", "custom_field_settings.project.name", "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "default_access_level", "default_view", "due_date", "due_on", "followers", "followers.name", "html_notes", "icon", "members", "members.name", "minimum_access_level_for_customization", "minimum_access_level_for_sharing", "modified_at", "name", "notes", "owner", "permalink_url", "privacy_setting", "project_brief", "public", "start_on", "team", "team.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Information about the followers being removed.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "followers" ], "properties": { "followers": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "521621,621373" } } } } } } } }, "responses": { "200": { "description": "Successfully removed followers from the project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "archived": { "description": "True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.", "type": "boolean", "example": false }, "color": { "description": "Color of the project.", "type": "string", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", "none", null ], "example": "light-green" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "current_status": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "*Deprecated: new integrations should prefer the `status_update` resource.*\nA *project status* is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: \"green\" for projects that are on track, \"yellow\" for projects at risk, and \"red\" for projects that are behind.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_status", "x-insert-after": "gid" }, "title": { "description": "The title of the project status update.", "type": "string", "example": "Status Update - Jun 15" } } }, { "type": "object", "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "color": { "description": "The color associated with the status update.", "type": "string", "enum": [ "green", "yellow", "red", "blue", "complete" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] }, { "type": "object", "nullable": true, "description": "*Deprecated: new integrations should prefer the `current_status_update` resource.*" } ] }, "current_status_update": { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "nullable": true, "description": "The latest `status_update` posted to this project." } ] }, "custom_field_settings": { "description": "

Full object requires scope: custom_fields:read

\n\nArray of Custom Field Settings (in compact form).", "readOnly": true, "type": "array", "items": { "allOf": [ { "description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field_setting", "x-insert-after": "gid" } } }, { "type": "object", "properties": { "project": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to.", "readOnly": true } ] }, "is_important": { "description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.", "type": "boolean", "readOnly": true, "example": false }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.", "readOnly": true } ] }, "custom_field": { "allOf": [ { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, { "type": "object", "description": "The custom field that is applied to the `parent`.", "readOnly": true } ] } } } ] } }, "default_view": { "description": "The default view (list, board, calendar, or timeline) of a project.", "type": "string", "enum": [ "list", "board", "calendar", "timeline" ], "example": "calendar" }, "due_date": { "description": "*Deprecated: new integrations should prefer the `due_on` field.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "due_on": { "description": "The day on which this project is due. This takes a date with format YYYY-MM-DD.", "type": "string", "nullable": true, "format": "date", "example": "2019-09-15" }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the project with formatting as HTML.", "type": "string", "example": "These are things we need to purchase." }, "members": { "description": "Array of users who are members of this project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project was last modified.\n*Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.*", "type": "string", "readOnly": true, "format": "date-time", "example": "2012-02-22T02:06:58.147Z" }, "notes": { "description": "Free-form textual information associated with the project (ie., its description).", "type": "string", "example": "These are things we need to purchase." }, "public": { "description": "*Deprecated:* new integrations use `privacy_setting` instead.", "type": "boolean", "deprecated": true, "example": false }, "privacy_setting": { "description": "The privacy setting of the project. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_to_workspace", "private_to_team", "private" ], "example": "public_to_workspace" }, "start_on": { "description": "The day on which work for this project begins, or null if the project has no start date. This takes a date with `YYYY-MM-DD` format. *Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "default_access_level": { "description": "The default access for users or teams who join or are added as members to the project.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "example": "admin" }, "minimum_access_level_for_customization": { "description": "The minimum access level needed for project members to modify this project's workflow and appearance.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" }, "minimum_access_level_for_sharing": { "description": "The minimum access level needed for project members to share the project and manage project memberships.", "type": "string", "enum": [ "admin", "editor" ], "example": "admin" } } } ] }, { "type": "object", "properties": { "custom_fields": { "description": "Array of Custom Fields.", "readOnly": true, "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } }, "completed": { "description": "True if the project is currently marked complete, false if not.", "type": "boolean", "readOnly": true, "example": false }, "completed_at": { "description": "The time at which this project was completed, or null if the project is not completed.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "description": "The user that marked this project complete, or null if the project is not completed.", "readOnly": true, "nullable": true } ] }, "followers": { "description": "Array of users following this project. Followers are a subset of members who have opted in to receive \"tasks added\" notifications for a project.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "owner": { "description": "The current owner of the project, may be null.", "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "nullable": true } ] }, "team": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "description": "The team that this project is shared with." } ] }, "icon": { "description": "The icon for a project.", "type": "string", "nullable": true, "enum": [ "list", "board", "timeline", "calendar", "rocket", "people", "graph", "star", "bug", "light_bulb", "globe", "gear", "notebook", "computer", "check", "target", "html", "megaphone", "chat_bubbles", "briefcase", "page_layout", "mountain_flag", "puzzle", "presentation", "line_and_symbols", "speed_dial", "ribbon", "shoe", "shopping_basket", "map", "ticket", "coins" ], "example": "chat_bubbles" }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/project/123456789" }, "project_brief": { "allOf": [ { "description": "A *Project Brief* allows you to explain the what and why of the project to your team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_brief", "x-insert-after": "gid" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project brief associated with this project.", "nullable": true } ] }, "created_from_template": { "allOf": [ { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, { "type": "object", "description": "[Opt In](/docs/inputoutput-options). The project template from which this project was created. If the project was not created from a template, this field will be null.", "nullable": true } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace or organization this project is associated with. Once created, projects cannot be moved to a different workspace. This attribute can only be specified at creation time. If the workspace for your project is an organization, you must also supply a `team` in the request body." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nProject result = client.projects.removeFollowersForProject(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the followers being removed.\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\"\n};\nprojectsApiInstance.removeFollowersForProject(body, project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.removeFollowersForProject(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the followers being removed.\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'opt_fields': \"archived,color,completed,completed_at,completed_by,completed_by.name,created_at,created_from_template,created_from_template.name,current_status,current_status.author,current_status.author.name,current_status.color,current_status.created_at,current_status.created_by,current_status.created_by.name,current_status.html_text,current_status.modified_at,current_status.text,current_status.title,current_status_update,current_status_update.resource_subtype,current_status_update.title,custom_field_settings,custom_field_settings.custom_field,custom_field_settings.custom_field.asana_created_field,custom_field_settings.custom_field.created_by,custom_field_settings.custom_field.created_by.name,custom_field_settings.custom_field.currency_code,custom_field_settings.custom_field.custom_label,custom_field_settings.custom_field.custom_label_position,custom_field_settings.custom_field.date_value,custom_field_settings.custom_field.date_value.date,custom_field_settings.custom_field.date_value.date_time,custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.description,custom_field_settings.custom_field.display_value,custom_field_settings.custom_field.enabled,custom_field_settings.custom_field.enum_options,custom_field_settings.custom_field.enum_options.color,custom_field_settings.custom_field.enum_options.enabled,custom_field_settings.custom_field.enum_options.name,custom_field_settings.custom_field.enum_value,custom_field_settings.custom_field.enum_value.color,custom_field_settings.custom_field.enum_value.enabled,custom_field_settings.custom_field.enum_value.name,custom_field_settings.custom_field.format,custom_field_settings.custom_field.has_notifications_enabled,custom_field_settings.custom_field.id_prefix,custom_field_settings.custom_field.input_restrictions,custom_field_settings.custom_field.is_formula_field,custom_field_settings.custom_field.is_global_to_workspace,custom_field_settings.custom_field.is_value_read_only,custom_field_settings.custom_field.multi_enum_values,custom_field_settings.custom_field.multi_enum_values.color,custom_field_settings.custom_field.multi_enum_values.enabled,custom_field_settings.custom_field.multi_enum_values.name,custom_field_settings.custom_field.name,custom_field_settings.custom_field.number_value,custom_field_settings.custom_field.people_value,custom_field_settings.custom_field.people_value.name,custom_field_settings.custom_field.precision,custom_field_settings.custom_field.privacy_setting,custom_field_settings.custom_field.reference_value,custom_field_settings.custom_field.reference_value.name,custom_field_settings.custom_field.representation_type,custom_field_settings.custom_field.resource_subtype,custom_field_settings.custom_field.text_value,custom_field_settings.custom_field.type,custom_field_settings.is_important,custom_field_settings.parent,custom_field_settings.parent.name,custom_field_settings.project,custom_field_settings.project.name,custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,default_access_level,default_view,due_date,due_on,followers,followers.name,html_notes,icon,members,members.name,minimum_access_level_for_customization,minimum_access_level_for_sharing,modified_at,name,notes,owner,permalink_url,privacy_setting,project_brief,public,start_on,team,team.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Remove followers from a project\n api_response = projects_api_instance.remove_followers_for_project(body, project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->remove_followers_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.remove_followers_for_project(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->removeFollowersForProject($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.remove_followers_for_project(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/saveAsTemplate": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Create a project template from a project", "description": "Creates and returns a job that will asynchronously handle the project template creation.", "tags": [ "Projects" ], "operationId": "projectSaveAsTemplate", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "new_graph_export", "new_graph_export.completed_at", "new_graph_export.created_at", "new_graph_export.download_url", "new_project", "new_project.name", "new_project_template", "new_project_template.name", "new_resource_export", "new_resource_export.completed_at", "new_resource_export.created_at", "new_resource_export.download_url", "new_task", "new_task.created_by", "new_task.name", "new_task.resource_subtype", "new_task_template", "new_task_template.name", "resource_subtype", "status" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "new_graph_export", "new_graph_export.completed_at", "new_graph_export.created_at", "new_graph_export.download_url", "new_project", "new_project.name", "new_project_template", "new_project_template.name", "new_resource_export", "new_resource_export.completed_at", "new_resource_export.created_at", "new_resource_export.download_url", "new_task", "new_task.created_by", "new_task.name", "new_task.resource_subtype", "new_task_template", "new_task_template.name", "resource_subtype", "status" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Describes the inputs used for creating a project template, such as the resulting project template's name, which team it should be created in.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "name", "public" ], "properties": { "name": { "description": "The name of the new project template.", "type": "string", "example": "New Project Template" }, "team": { "description": "Sets the team of the new project template. If the project exists in an organization, specify team and not workspace.", "type": "string", "example": "12345" }, "workspace": { "description": "Sets the workspace of the new project template. Only specify workspace if the project exists in a workspace.", "type": "string", "example": "12345" }, "public": { "description": "Sets the project template to public to its team.", "type": "boolean", "example": true } } } } } } } }, "responses": { "201": { "description": "Successfully created the job to handle project template creation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A *job* is an object representing a process that handles asynchronous work.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "job", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "duplicate_task" }, "status": { "description": "The current status of this job.", "type": "string", "enum": [ "not_started", "in_progress", "succeeded", "failed" ], "readOnly": true, "example": "in_progress" }, "new_project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "new_task": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "nullable": true } ] }, "new_project_template": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, "new_graph_export": { "description": "A *graph_export* object represents a request to export the data starting from a parent object", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "graph_export", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin JSON format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or\nfailed. If present, this URL may only be valid for 1 hour from\nthe time of retrieval. You should avoid persisting this URL\nsomewhere and rather refresh on demand to ensure you do not keep\nstale URLs.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/domain_export/7588024658887731/download/ domain_export_2563645399633793_7588024658887731_2023018-201726.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Content-Sha256=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host&x-id=GetObject#_=_" }, "completed_at": { "description": "The time at which this resource was completed.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } }, "new_resource_export": { "description": "A *resource_export* object represents a request to bulk export objects for one or more resources.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "export_request", "x-insert-after": "gid" }, "created_at": { "description": "The time at which the resource export object was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin [JSON Lines](https://jsonlines.org/) format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or failed.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/object_export/7588024658887731/download/ object_export_2563645399633793_7588024658887731_2023018-201726.jsonl.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Credential=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host" }, "completed_at": { "description": "The time at which this resource was completed. This will be null if the export is still in progress.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJob result = client.projects.projectSaveAsTemplate(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet projectsApiInstance = new Asana.ProjectsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Describes the inputs used for creating a project template, such as the resulting project template's name, which team it should be created in.\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'opt_fields': \"new_graph_export,new_graph_export.completed_at,new_graph_export.created_at,new_graph_export.download_url,new_project,new_project.name,new_project_template,new_project_template.name,new_resource_export,new_resource_export.completed_at,new_resource_export.created_at,new_resource_export.download_url,new_task,new_task.created_by,new_task.name,new_task.resource_subtype,resource_subtype,status\"\n};\nprojectsApiInstance.projectSaveAsTemplate(body, project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.projects.projectSaveAsTemplate(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nprojects_api_instance = asana.ProjectsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Describes the inputs used for creating a project template, such as the resulting project template's name, which team it should be created in.\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'opt_fields': \"new_graph_export,new_graph_export.completed_at,new_graph_export.created_at,new_graph_export.download_url,new_project,new_project.name,new_project_template,new_project_template.name,new_resource_export,new_resource_export.completed_at,new_resource_export.created_at,new_resource_export.download_url,new_task,new_task.created_by,new_task.name,new_task.resource_subtype,resource_subtype,status\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a project template from a project\n api_response = projects_api_instance.project_save_as_template(body, project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling ProjectsApi->project_save_as_template: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.projects.project_save_as_template(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "projects->projectSaveAsTemplate($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.projects.project_save_as_template(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 4, "x-moar-complexity-skipped": false } }, "/reactions": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get reactions with an emoji base on an object.", "description": "Returns the reactions with a specified emoji base character on the object.", "operationId": "getReactionsOnObject", "tags": [ "Reactions" ], "parameters": [ { "name": "target", "required": true, "in": "query", "description": "Globally unique identifier for object to fetch reactions from. Must be a GID for a status update or story.", "schema": { "type": "string" }, "example": "159874" }, { "name": "emoji_base", "required": true, "in": "query", "description": "Only return reactions with this emoji base character.", "schema": { "type": "string" }, "example": "\ud83d\udc4d" } ], "responses": { "200": { "description": "Successfully retrieved the specified object's reactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "An emoji reaction on an object.", "properties": { "gid": { "description": "The ID of the reaction object.", "type": "string", "example": "12345" }, "emoji": { "description": "The emoji string used in the reaction.", "type": "string", "example": "\ud83d\udc4d" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet reactionsApiInstance = new Asana.ReactionsApi();\nlet target = \"159874\"; // String | Globally unique identifier for object to fetch reactions from. Must be a GID for a status update or story.\nlet emoji_base = \"\ud83d\udc4d\"; // String | Only return reactions with this emoji base character.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\"\n};\nreactionsApiInstance.getReactionsOnObject(target, emoji_base, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nreactions_api_instance = asana.ReactionsApi(api_client)\ntarget = \"159874\" # str | Globally unique identifier for object to fetch reactions from. Must be a GID for a status update or story.\nemoji_base = \"\ud83d\udc4d\" # str | Only return reactions with this emoji base character.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n}\n\ntry:\n # Get reactions with an emoji base on an object.\n api_response = reactions_api_instance.get_reactions_on_object(target, emoji_base, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling ReactionsApi->get_reactions_on_object: %s\\n\" % e)", "name": "python-sdk-v5" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/rule_triggers/{rule_trigger_gid}/run": { "parameters": [ { "name": "rule_trigger_gid", "in": "path", "required": true, "description": "The ID of the incoming web request trigger. This value is a path parameter that is automatically generated for the API endpoint.", "schema": { "type": "string" }, "example": "12345", "x-env-variable": "rule" } ], "post": { "summary": "Trigger a rule", "description": "Trigger a rule which uses an [\"incoming web request\"](/docs/incoming-web-requests) trigger.", "tags": [ "Rules" ], "operationId": "triggerRule", "requestBody": { "description": "A dictionary of variables accessible from within the rule.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "resource": { "description": "The ID of the resource. For the duration of the beta, this resource is always a task, and this task must exist in the project in which the rule is created.", "type": "string", "example": "12345" }, "action_data": { "type": "object", "additionalProperties": true, "description": "The dynamic keys and values of the request. These fields are intended to be used in the action for the rule associated with this trigger.", "example": { "jira_ticket_name": "Test", "jira_ticket_id": "123" } } }, "required": [ "resource", "action_data" ] } } } } } }, "responses": { "200": { "description": "Successfully triggered a rule.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "description": "Message providing more detail about the result", "type": "string", "example": "Successfully saved the payload and ran the rule" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet rulesApiInstance = new Asana.RulesApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | A dictionary of variables accessible from within the rule.\nlet rule_trigger_gid = \"12345\"; // String | The ID of the incoming web request trigger. This value is a path parameter that is automatically generated for the API endpoint.\n\nrulesApiInstance.triggerRule(body, rule_trigger_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.rules.triggerRule(ruleTriggerGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nrules_api_instance = asana.RulesApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | A dictionary of variables accessible from within the rule.\nrule_trigger_gid = \"12345\" # str | The ID of the incoming web request trigger. This value is a path parameter that is automatically generated for the API endpoint.\n\n\ntry:\n # Trigger a rule\n api_response = rules_api_instance.trigger_rule(body, rule_trigger_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling RulesApi->trigger_rule: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.rules.trigger_rule(rule_trigger_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/sections/{section_gid}": { "parameters": [ { "name": "section_gid", "in": "path", "required": true, "description": "The globally unique identifier for the section.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "section" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a section", "description": "Returns the complete record for a single section.", "tags": [ "Sections" ], "operationId": "getSection", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "created_at", "name", "project", "project.name", "projects", "projects.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "name", "project", "project.name", "projects", "projects.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved section.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "projects": { "description": "*Deprecated - please use project instead*", "type": "array", "readOnly": true, "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nSection result = client.sections.getSection(sectionGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet sectionsApiInstance = new Asana.SectionsApi();\nlet section_gid = \"321654\"; // String | The globally unique identifier for the section.\nlet opts = { \n 'opt_fields': \"created_at,name,project,project.name,projects,projects.name\"\n};\nsectionsApiInstance.getSection(section_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.sections.getSection(sectionGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nsections_api_instance = asana.SectionsApi(api_client)\nsection_gid = \"321654\" # str | The globally unique identifier for the section.\nopts = {\n 'opt_fields': \"created_at,name,project,project.name,projects,projects.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a section\n api_response = sections_api_instance.get_section(section_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling SectionsApi->get_section: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.sections.get_section(section_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "sections->getSection($section_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.sections.get_section(section_gid: 'section_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a section", "description": "A specific, existing section can be updated by making a PUT request on\nthe URL for that project. Only the fields provided in the `data` block\nwill be updated; any unspecified fields will remain unchanged. (note that\nat this time, the only field that can be updated is the `name` field.)\n\nWhen using this method, it is best to specify only those fields you wish\nto change, or else you may overwrite changes made by another user since\nyou last retrieved the task.\n\nReturns the complete updated section record.", "tags": [ "Sections" ], "operationId": "updateSection", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "created_at", "name", "project", "project.name", "projects", "projects.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "name", "project", "project.name", "projects", "projects.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The section to create.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "description": "The text to be displayed as the section name. This cannot be an empty string.", "type": "string", "example": "Next Actions" }, "insert_before": { "description": "An existing section within this project before which the added section should be inserted. Cannot be provided together with insert_after.", "type": "string", "example": "86420" }, "insert_after": { "description": "An existing section within this project after which the added section should be inserted. Cannot be provided together with insert_before.", "type": "string", "example": "987654" } }, "required": [ "name" ] } } } } } }, "responses": { "200": { "description": "Successfully updated the specified section.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "projects": { "description": "*Deprecated - please use project instead*", "type": "array", "readOnly": true, "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nSection result = client.sections.updateSection(sectionGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet sectionsApiInstance = new Asana.SectionsApi();\nlet section_gid = \"321654\"; // String | The globally unique identifier for the section.\nlet opts = { \n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, \n 'opt_fields': \"created_at,name,project,project.name,projects,projects.name\"\n};\nsectionsApiInstance.updateSection(section_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.sections.updateSection(sectionGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nsections_api_instance = asana.SectionsApi(api_client)\nsection_gid = \"321654\" # str | The globally unique identifier for the section.\nopts = {\n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, # dict | The section to create.\n 'opt_fields': \"created_at,name,project,project.name,projects,projects.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a section\n api_response = sections_api_instance.update_section(section_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling SectionsApi->update_section: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.sections.update_section(section_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "sections->updateSection($section_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.sections.update_section(section_gid: 'section_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 3, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a section", "description": "A specific, existing section can be deleted by making a DELETE request on\nthe URL for that section.\n\nNote that sections must be empty to be deleted.\n\nThe last remaining section cannot be deleted.\n\nReturns an empty data block.", "tags": [ "Sections" ], "operationId": "deleteSection", "responses": { "200": { "description": "Successfully deleted the specified section.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.sections.deleteSection(sectionGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet sectionsApiInstance = new Asana.SectionsApi();\nlet section_gid = \"321654\"; // String | The globally unique identifier for the section.\n\nsectionsApiInstance.deleteSection(section_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.sections.deleteSection(sectionGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nsections_api_instance = asana.SectionsApi(api_client)\nsection_gid = \"321654\" # str | The globally unique identifier for the section.\n\n\ntry:\n # Delete a section\n api_response = sections_api_instance.delete_section(section_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling SectionsApi->delete_section: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.sections.delete_section(section_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "sections->deleteSection($section_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.sections.delete_section(section_gid: 'section_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/sections": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get sections in a project", "description": "Returns the compact records for all sections in the specified project.", "tags": [ "Sections" ], "operationId": "getSectionsForProject", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "created_at", "name", "offset", "path", "project", "project.name", "projects", "projects.name", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "name", "offset", "path", "project", "project.name", "projects", "projects.name", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved sections in project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList
result = client.sections.getSectionsForProject(projectGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet sectionsApiInstance = new Asana.SectionsApi();\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"created_at,name,offset,path,project,project.name,projects,projects.name,uri\"\n};\nsectionsApiInstance.getSectionsForProject(project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.sections.getSectionsForProject(projectGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nsections_api_instance = asana.SectionsApi(api_client)\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"created_at,name,offset,path,project,project.name,projects,projects.name,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get sections in a project\n api_response = sections_api_instance.get_sections_for_project(project_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling SectionsApi->get_sections_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.sections.get_sections_for_project(project_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "sections->getSectionsForProject($project_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.sections.get_sections_for_project(project_gid: 'project_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a section in a project", "description": "Creates a new section in a project.\nReturns the full record of the newly created section.", "tags": [ "Sections" ], "operationId": "createSectionForProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "created_at", "name", "project", "project.name", "projects", "projects.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "name", "project", "project.name", "projects", "projects.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The section to create.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "description": "The text to be displayed as the section name. This cannot be an empty string.", "type": "string", "example": "Next Actions" }, "insert_before": { "description": "An existing section within this project before which the added section should be inserted. Cannot be provided together with insert_after.", "type": "string", "example": "86420" }, "insert_after": { "description": "An existing section within this project after which the added section should be inserted. Cannot be provided together with insert_before.", "type": "string", "example": "987654" } }, "required": [ "name" ] } } } } } }, "responses": { "201": { "description": "Successfully created the specified section.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "projects": { "description": "*Deprecated - please use project instead*", "type": "array", "readOnly": true, "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nSection result = client.sections.createSectionForProject(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet sectionsApiInstance = new Asana.SectionsApi();\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, \n 'opt_fields': \"created_at,name,project,project.name,projects,projects.name\"\n};\nsectionsApiInstance.createSectionForProject(project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.sections.createSectionForProject(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nsections_api_instance = asana.SectionsApi(api_client)\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, # dict | The section to create.\n 'opt_fields': \"created_at,name,project,project.name,projects,projects.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a section in a project\n api_response = sections_api_instance.create_section_for_project(project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling SectionsApi->create_section_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.sections.create_section_for_project(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "sections->createSectionForProject($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.sections.create_section_for_project(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 3, "x-moar-complexity-skipped": false } }, "/sections/{section_gid}/addTask": { "parameters": [ { "name": "section_gid", "in": "path", "required": true, "description": "The globally unique identifier for the section.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "section" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add task to section", "description": "Required scope: tasks:write\n\nAdd a task to a specific, existing section. This will remove the task from other sections of the project.\n\nThe task will be inserted at the top of a section unless an insert_before or insert_after parameter is declared.\n\nThis does not work for separators (tasks with the resource_subtype of section).", "tags": [ "Sections" ], "operationId": "addTaskForSection", "requestBody": { "description": "The task and optionally the insert location.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "task": { "description": "The task to add to this section.", "type": "string", "example": "123456" }, "insert_before": { "description": "An existing task within this section before which the added task should be inserted. Cannot be provided together with insert_after.", "type": "string", "example": "86420" }, "insert_after": { "description": "An existing task within this section after which the added task should be inserted. Cannot be provided together with insert_before.", "type": "string", "example": "987654" } }, "required": [ "task" ] } } } } } }, "responses": { "200": { "description": "Successfully added the task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.sections.addTaskForSection(sectionGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet sectionsApiInstance = new Asana.SectionsApi();\nlet section_gid = \"321654\"; // String | The globally unique identifier for the section.\nlet opts = { \n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}\n};\nsectionsApiInstance.addTaskForSection(section_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.sections.addTaskForSection(sectionGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nsections_api_instance = asana.SectionsApi(api_client)\nsection_gid = \"321654\" # str | The globally unique identifier for the section.\nopts = {\n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, # dict | The task and optionally the insert location.\n}\n\ntry:\n # Add task to section\n api_response = sections_api_instance.add_task_for_section(section_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling SectionsApi->add_task_for_section: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.sections.add_task_for_section(section_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "sections->addTaskForSection($section_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.sections.add_task_for_section(section_gid: 'section_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 3, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/sections/insert": { "parameters": [ { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Move or Insert sections", "description": "Move sections relative to each other. One of\n`before_section` or `after_section` is required.\n\nSections cannot be moved between projects.\n\nReturns an empty data block.", "tags": [ "Sections" ], "operationId": "insertSectionForProject", "requestBody": { "description": "The section's move action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "section": { "description": "The section to reorder.", "type": "string", "example": "321654" }, "before_section": { "description": "Insert the given section immediately before the section specified by this parameter.", "type": "string", "example": "86420" }, "after_section": { "description": "Insert the given section immediately after the section specified by this parameter.", "type": "string", "example": "987654" } }, "required": [ "section" ] } } } } } }, "responses": { "200": { "description": "Successfully moved the specified section.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.sections.insertSectionForProject(projectGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet sectionsApiInstance = new Asana.SectionsApi();\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}\n};\nsectionsApiInstance.insertSectionForProject(project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.sections.insertSectionForProject(projectGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nsections_api_instance = asana.SectionsApi(api_client)\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, # dict | The section's move action.\n}\n\ntry:\n # Move or Insert sections\n api_response = sections_api_instance.insert_section_for_project(project_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling SectionsApi->insert_section_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.sections.insert_section_for_project(project_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "sections->insertSectionForProject($project_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.sections.insert_section_for_project(project_gid: 'project_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 3, "x-moar-complexity-skipped": false } }, "/status_updates/{status_update_gid}": { "parameters": [ { "name": "status_update_gid", "in": "path", "required": true, "description": "The status update to get.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "status" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a status update", "description": "Returns the complete record for a single status update.", "tags": [ "Status updates" ], "operationId": "getStatus", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "author", "author.name", "created_at", "created_by", "created_by.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "liked", "likes", "likes.user", "likes.user.name", "modified_at", "num_hearts", "num_likes", "parent", "parent.name", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "status_type", "text", "title" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "author", "author.name", "created_at", "created_by", "created_by.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "liked", "likes", "likes.user", "likes.user.name", "modified_at", "num_hearts", "num_likes", "parent", "parent.name", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "status_type", "text", "title" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified object's status updates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "required": [ "text", "status_type" ], "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "status_type": { "description": "The type associated with the status update. This represents the current state of the object this object is on.", "type": "string", "enum": [ "on_track", "at_risk", "off_track", "on_hold", "complete", "achieved", "partial", "missed", "dropped" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "hearted": { "description": "*Deprecated - please use liked instead* True if the status is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this status.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "liked": { "description": "True if the status is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this status.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "reaction_summary": { "description": "Summary of emoji reactions on this status.", "type": "array", "items": { "type": "object", "description": "A summary of an emoji reaction on an object.", "properties": { "emoji_base": { "description": "The emoji base character used in the reaction.", "type": "string", "example": "\ud83d\udc4e" }, "variant": { "description": "The full emoji string used in the reaction.", "type": "string", "example": "\ud83d\udc4e\ud83c\udffc" }, "count": { "description": "The number of reactions with the emoji variant on the object.", "type": "number", "example": 1 }, "reacted": { "description": "Whether the current user has reacted with the emoji variant on the object.", "type": "boolean", "example": false } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this status.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this status.", "type": "integer", "example": 5, "readOnly": true }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent of the status update. This can be a project, goal or portfolio, and indicates that this status was sent on that object." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.statusupdates.getStatus(statusGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet statusUpdatesApiInstance = new Asana.StatusUpdatesApi();\nlet status_update_gid = \"321654\"; // String | The status update to get.\nlet opts = { \n 'opt_fields': \"author,author.name,created_at,created_by,created_by.name,hearted,hearts,hearts.user,hearts.user.name,html_text,liked,likes,likes.user,likes.user.name,modified_at,num_hearts,num_likes,parent,parent.name,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,status_type,text,title\"\n};\nstatusUpdatesApiInstance.getStatus(status_update_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.statusupdates.getStatus(statusUpdateGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nstatus_updates_api_instance = asana.StatusUpdatesApi(api_client)\nstatus_update_gid = \"321654\" # str | The status update to get.\nopts = {\n 'opt_fields': \"author,author.name,created_at,created_by,created_by.name,hearted,hearts,hearts.user,hearts.user.name,html_text,liked,likes,likes.user,likes.user.name,modified_at,num_hearts,num_likes,parent,parent.name,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,status_type,text,title\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a status update\n api_response = status_updates_api_instance.get_status(status_update_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling StatusUpdatesApi->get_status: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.status_updates.get_status(status_update_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "statusupdates->getStatus($status_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.status_updates.get_status(status_gid: 'status_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a status update", "description": "Deletes a specific, existing status update.\n\nReturns an empty data record.", "tags": [ "Status updates" ], "operationId": "deleteStatus", "responses": { "200": { "description": "Successfully deleted the specified status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.statusupdates.deleteStatus(statusGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet statusUpdatesApiInstance = new Asana.StatusUpdatesApi();\nlet status_update_gid = \"321654\"; // String | The status update to get.\n\nstatusUpdatesApiInstance.deleteStatus(status_update_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.statusupdates.deleteStatus(statusUpdateGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nstatus_updates_api_instance = asana.StatusUpdatesApi(api_client)\nstatus_update_gid = \"321654\" # str | The status update to get.\n\n\ntry:\n # Delete a status update\n api_response = status_updates_api_instance.delete_status(status_update_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling StatusUpdatesApi->delete_status: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.status_updates.delete_status(status_update_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "statusupdates->deleteStatus($status_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.status_updates.delete_status(status_gid: 'status_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/status_updates": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get status updates from an object", "description": "Returns the compact status update records for all updates on the object.", "tags": [ "Status updates" ], "operationId": "getStatusesForObject", "parameters": [ { "name": "parent", "required": true, "in": "query", "description": "Globally unique identifier for object to fetch statuses from. Must be a GID for a project, portfolio, or goal.", "schema": { "type": "string" }, "example": "159874" }, { "name": "created_since", "in": "query", "description": "Only return statuses that have been created since the given time.", "schema": { "type": "string", "format": "date-time" }, "example": "2012-02-22T02:06:58.158Z" }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "author", "author.name", "created_at", "created_by", "created_by.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "liked", "likes", "likes.user", "likes.user.name", "modified_at", "num_hearts", "num_likes", "offset", "parent", "parent.name", "path", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "status_type", "text", "title", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "author", "author.name", "created_at", "created_by", "created_by.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "liked", "likes", "likes.user", "likes.user.name", "modified_at", "num_hearts", "num_likes", "offset", "parent", "parent.name", "path", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "status_type", "text", "title", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified object's status updates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.statusupdates.getStatusesForObject(createdSince, parent)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet statusUpdatesApiInstance = new Asana.StatusUpdatesApi();\nlet parent = \"159874\"; // String | Globally unique identifier for object to fetch statuses from. Must be a GID for a project, portfolio, or goal.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'created_since': \"2012-02-22T02:06:58.158Z\", \n 'opt_fields': \"author,author.name,created_at,created_by,created_by.name,hearted,hearts,hearts.user,hearts.user.name,html_text,liked,likes,likes.user,likes.user.name,modified_at,num_hearts,num_likes,offset,parent,parent.name,path,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,status_type,text,title,uri\"\n};\nstatusUpdatesApiInstance.getStatusesForObject(parent, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.statusupdates.getStatusesForObject({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nstatus_updates_api_instance = asana.StatusUpdatesApi(api_client)\nparent = \"159874\" # str | Globally unique identifier for object to fetch statuses from. Must be a GID for a project, portfolio, or goal.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'created_since': '2012-02-22T02:06:58.158Z', # datetime | Only return statuses that have been created since the given time.\n 'opt_fields': \"author,author.name,created_at,created_by,created_by.name,hearted,hearts,hearts.user,hearts.user.name,html_text,liked,likes,likes.user,likes.user.name,modified_at,num_hearts,num_likes,offset,parent,parent.name,path,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,status_type,text,title,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get status updates from an object\n api_response = status_updates_api_instance.get_statuses_for_object(parent, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling StatusUpdatesApi->get_statuses_for_object: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.status_updates.get_statuses_for_object({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "statusupdates->getStatusesForObject(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.status_updates.get_statuses_for_object(parent: ''parent_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a status update", "description": "Creates a new status update on an object.\nReturns the full record of the newly created status update.", "tags": [ "Status updates" ], "operationId": "createStatusForObject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "author", "author.name", "created_at", "created_by", "created_by.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "liked", "likes", "likes.user", "likes.user.name", "modified_at", "num_hearts", "num_likes", "parent", "parent.name", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "status_type", "text", "title" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "author", "author.name", "created_at", "created_by", "created_by.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "liked", "likes", "likes.user", "likes.user.name", "modified_at", "num_hearts", "num_likes", "parent", "parent.name", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "status_type", "text", "title" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The status update to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "required": [ "text", "status_type" ], "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "status_type": { "description": "The type associated with the status update. This represents the current state of the object this object is on.", "type": "string", "enum": [ "on_track", "at_risk", "off_track", "on_hold", "complete", "achieved", "partial", "missed", "dropped" ] } } } ] }, { "type": "object", "required": [ "parent" ], "properties": { "parent": { "allOf": [ { "type": "string", "description": "The id of parent to send this status update to. This can be a project, goal or portfolio." } ] } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created a new status update.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "status_update", "x-insert-after": "gid" }, "title": { "description": "The title of the status update.", "type": "string", "example": "Status Update - Jun 15" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe `resource_subtype`s for `status` objects represent the type of their parent.", "enum": [ "project_status_update", "portfolio_status_update", "goal_status_update" ], "example": "project_status_update", "readOnly": true } } }, { "type": "object", "required": [ "text", "status_type" ], "properties": { "text": { "description": "The text content of the status update.", "type": "string", "example": "The project is moving forward according to plan..." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). The text content of the status update with formatting as HTML.", "type": "string", "example": "The project is moving forward according to plan..." }, "status_type": { "description": "The type associated with the status update. This represents the current state of the object this object is on.", "type": "string", "enum": [ "on_track", "at_risk", "off_track", "on_hold", "complete", "achieved", "partial", "missed", "dropped" ] } } } ] }, { "type": "object", "properties": { "author": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "hearted": { "description": "*Deprecated - please use liked instead* True if the status is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this status.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "liked": { "description": "True if the status is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this status.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "reaction_summary": { "description": "Summary of emoji reactions on this status.", "type": "array", "items": { "type": "object", "description": "A summary of an emoji reaction on an object.", "properties": { "emoji_base": { "description": "The emoji base character used in the reaction.", "type": "string", "example": "\ud83d\udc4e" }, "variant": { "description": "The full emoji string used in the reaction.", "type": "string", "example": "\ud83d\udc4e\ud83c\udffc" }, "count": { "description": "The number of reactions with the emoji variant on the object.", "type": "number", "example": 1 }, "reacted": { "description": "Whether the current user has reacted with the emoji variant on the object.", "type": "boolean", "example": false } } }, "readOnly": true }, "modified_at": { "description": "The time at which this project status was last modified.\n*Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the status.*", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this status.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this status.", "type": "integer", "example": 5, "readOnly": true }, "parent": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The parent of the status update. This can be a project, goal or portfolio, and indicates that this status was sent on that object." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.statusupdates.createStatusForObject()\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet statusUpdatesApiInstance = new Asana.StatusUpdatesApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The status update to create.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"author,author.name,created_at,created_by,created_by.name,hearted,hearts,hearts.user,hearts.user.name,html_text,liked,likes,likes.user,likes.user.name,modified_at,num_hearts,num_likes,parent,parent.name,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,status_type,text,title\"\n};\nstatusUpdatesApiInstance.createStatusForObject(body, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.statusupdates.createStatusForObject({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nstatus_updates_api_instance = asana.StatusUpdatesApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The status update to create.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"author,author.name,created_at,created_by,created_by.name,hearted,hearts,hearts.user,hearts.user.name,html_text,liked,likes,likes.user,likes.user.name,modified_at,num_hearts,num_likes,parent,parent.name,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,status_type,text,title\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a status update\n api_response = status_updates_api_instance.create_status_for_object(body, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling StatusUpdatesApi->create_status_for_object: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.status_updates.create_status_for_object({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "statusupdates->createStatusForObject(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.status_updates.create_status_for_object(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 8, "x-moar-complexity-skipped": false } }, "/stories/{story_gid}": { "parameters": [ { "name": "story_gid", "in": "path", "description": "Globally unique identifier for the story.", "required": true, "schema": { "type": "string" }, "example": "35678", "x-env-variable": "story" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a story", "description": "Required scope: stories:read\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
FieldRequired Scope
previewsattachments:read
attachmentsattachments:read
\n\nReturns the full record for a single story.", "tags": [ "Stories" ], "operationId": "getStory", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "assignee", "assignee.name", "created_at", "created_by", "created_by.name", "custom_field", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.representation_type", "custom_field.text_value", "custom_field.type", "dependency", "dependency.created_by", "dependency.name", "dependency.resource_subtype", "duplicate_of", "duplicate_of.created_by", "duplicate_of.name", "duplicate_of.resource_subtype", "duplicated_from", "duplicated_from.created_by", "duplicated_from.name", "duplicated_from.resource_subtype", "follower", "follower.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "is_editable", "is_edited", "is_pinned", "liked", "likes", "likes.user", "likes.user.name", "new_approval_status", "new_date_value", "new_dates", "new_dates.due_at", "new_dates.due_on", "new_dates.start_on", "new_enum_value", "new_enum_value.color", "new_enum_value.enabled", "new_enum_value.name", "new_multi_enum_values", "new_multi_enum_values.color", "new_multi_enum_values.enabled", "new_multi_enum_values.name", "new_name", "new_number_value", "new_people_value", "new_people_value.name", "new_resource_subtype", "new_section", "new_section.name", "new_text_value", "num_hearts", "num_likes", "old_approval_status", "old_date_value", "old_dates", "old_dates.due_at", "old_dates.due_on", "old_dates.start_on", "old_enum_value", "old_enum_value.color", "old_enum_value.enabled", "old_enum_value.name", "old_multi_enum_values", "old_multi_enum_values.color", "old_multi_enum_values.enabled", "old_multi_enum_values.name", "old_name", "old_number_value", "old_people_value", "old_people_value.name", "old_resource_subtype", "old_section", "old_section.name", "old_text_value", "previews", "previews.fallback", "previews.footer", "previews.header", "previews.header_link", "previews.html_text", "previews.text", "previews.title", "previews.title_link", "project", "project.name", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "source", "sticker_name", "story", "story.created_at", "story.created_by", "story.created_by.name", "story.resource_subtype", "story.text", "tag", "tag.name", "target", "target.created_by", "target.name", "target.resource_subtype", "task", "task.created_by", "task.name", "task.resource_subtype", "text", "type" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "assignee", "assignee.name", "created_at", "created_by", "created_by.name", "custom_field", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.representation_type", "custom_field.text_value", "custom_field.type", "dependency", "dependency.created_by", "dependency.name", "dependency.resource_subtype", "duplicate_of", "duplicate_of.created_by", "duplicate_of.name", "duplicate_of.resource_subtype", "duplicated_from", "duplicated_from.created_by", "duplicated_from.name", "duplicated_from.resource_subtype", "follower", "follower.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "is_editable", "is_edited", "is_pinned", "liked", "likes", "likes.user", "likes.user.name", "new_approval_status", "new_date_value", "new_dates", "new_dates.due_at", "new_dates.due_on", "new_dates.start_on", "new_enum_value", "new_enum_value.color", "new_enum_value.enabled", "new_enum_value.name", "new_multi_enum_values", "new_multi_enum_values.color", "new_multi_enum_values.enabled", "new_multi_enum_values.name", "new_name", "new_number_value", "new_people_value", "new_people_value.name", "new_resource_subtype", "new_section", "new_section.name", "new_text_value", "num_hearts", "num_likes", "old_approval_status", "old_date_value", "old_dates", "old_dates.due_at", "old_dates.due_on", "old_dates.start_on", "old_enum_value", "old_enum_value.color", "old_enum_value.enabled", "old_enum_value.name", "old_multi_enum_values", "old_multi_enum_values.color", "old_multi_enum_values.enabled", "old_multi_enum_values.name", "old_name", "old_number_value", "old_people_value", "old_people_value.name", "old_resource_subtype", "old_section", "old_section.name", "old_text_value", "previews", "previews.fallback", "previews.footer", "previews.header", "previews.header_link", "previews.html_text", "previews.text", "previews.title", "previews.title_link", "project", "project.name", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "source", "sticker_name", "story", "story.created_at", "story.created_by", "story.created_by.name", "story.resource_subtype", "story.text", "tag", "tag.name", "target", "target.created_by", "target.name", "target.resource_subtype", "task", "task.created_by", "task.name", "task.resource_subtype", "text", "type" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified story.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A story represents an activity associated with an object in the Asana system.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "story", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "comment_added" }, "text": { "description": "The plain text of the comment to add. Cannot be used with html_text.", "type": "string", "example": "This is a comment." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). HTML formatted text for a comment. This will not include the name of the creator.", "type": "string", "example": "This is a comment." }, "is_pinned": { "description": "*Conditional*. Whether the story should be pinned on the resource.", "type": "boolean", "example": false }, "sticker_name": { "description": "The name of the sticker in this story. `null` if there is no sticker.", "type": "string", "enum": [ "green_checkmark", "people_dancing", "dancing_unicorn", "heart", "party_popper", "people_waving_flags", "splashing_narwhal", "trophy", "yeti_riding_unicorn", "celebrating_people", "determined_climbers", "phoenix_spreading_love" ], "example": "dancing_unicorn" } } }, { "type": "object", "properties": { "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "type": { "type": "string", "enum": [ "comment", "system" ], "readOnly": true, "example": "comment" }, "is_editable": { "description": "*Conditional*. Whether the text of the story can be edited after creation.", "type": "boolean", "readOnly": true, "example": false }, "is_edited": { "description": "*Conditional*. Whether the text of the story has been edited after creation.", "type": "boolean", "readOnly": true, "example": false }, "hearted": { "description": "*Deprecated - please use likes instead*\n*Conditional*. True if the story is hearted by the authorized user, false if not.", "type": "boolean", "readOnly": true, "example": false }, "hearts": { "description": "*Deprecated - please use likes instead*\n\n*Conditional*. Array of likes for users who have hearted this story.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_hearts": { "description": "*Deprecated - please use likes instead*\n\n*Conditional*. The number of users who have hearted this story.", "type": "integer", "readOnly": true, "example": 5 }, "liked": { "description": "*Conditional*. True if the story is liked by the authorized user, false if not.", "type": "boolean", "readOnly": true, "example": false }, "likes": { "description": "*Conditional*. Array of likes for users who have liked this story.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_likes": { "description": "*Conditional*. The number of users who have liked this story.", "type": "integer", "readOnly": true, "example": 5 }, "reaction_summary": { "description": "Summary of emoji reactions on this story.", "type": "array", "items": { "type": "object", "description": "A summary of an emoji reaction on an object.", "properties": { "emoji_base": { "description": "The emoji base character used in the reaction.", "type": "string", "example": "\ud83d\udc4e" }, "variant": { "description": "The full emoji string used in the reaction.", "type": "string", "example": "\ud83d\udc4e\ud83c\udffc" }, "count": { "description": "The number of reactions with the emoji variant on the object.", "type": "number", "example": 1 }, "reacted": { "description": "Whether the current user has reacted with the emoji variant on the object.", "type": "boolean", "example": false } } }, "readOnly": true }, "previews": { "description": "

Full object requires scope: attachments:read

\n\n*Conditional*. A collection of previews to be displayed in the story.\n\n*Note: This property only exists for comment stories.*", "type": "array", "items": { "type": "object", "description": "A collection of rich text that will be displayed as a preview to another app.\n\nThis is read-only except for a small group of whitelisted apps.", "readOnly": true, "properties": { "fallback": { "description": "Some fallback text to display if unable to display the full preview.", "type": "string", "example": "Greg: Great! I like this idea.\\n\\nhttps//a_company.slack.com/archives/ABCDEFG/12345678" }, "footer": { "description": "Text to display in the footer.", "type": "string", "example": "Mar 17, 2019 1:25 PM" }, "header": { "description": "Text to display in the header.", "type": "string", "example": "Asana for Slack" }, "header_link": { "description": "Where the header will link to.", "type": "string", "example": "https://asana.comn/apps/slack" }, "html_text": { "description": "HTML formatted text for the body of the preview.", "type": "string", "example": "Great! I like this idea." }, "text": { "description": "Text for the body of the preview.", "type": "string", "example": "Great! I like this idea." }, "title": { "description": "Text to display as the title.", "type": "string", "example": "Greg" }, "title_link": { "description": "Where to title will link to.", "type": "string", "example": "https://asana.slack.com/archives/ABCDEFG/12345678" } } }, "readOnly": true }, "old_name": { "description": "*Conditional* The previous name of the task before a name change.", "type": "string", "example": "This was the old name" }, "new_name": { "description": "*Conditional* The updated name of the task after a name change.", "type": "string", "nullable": true, "readOnly": true, "example": "This is the new name" }, "old_dates": { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, "new_dates": { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, "old_resource_subtype": { "description": "*Conditional*", "type": "string", "readOnly": true, "example": "default_task" }, "new_resource_subtype": { "description": "*Conditional*", "type": "string", "readOnly": true, "example": "milestone" }, "story": { "description": "A story represents an activity associated with an object in the Asana system.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "story", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "comment_added" }, "text": { "description": "*Create-only*. Human-readable text for the story or comment.\nThis will not include the name of the creator.\n*Note: This is not guaranteed to be stable for a given type of story. For example, text for a reassignment may not always say \u201cassigned to \u2026\u201d as the text for a story can both be edited and change based on the language settings of the user making the request.*\nUse the `resource_subtype` property to discover the action that created the story.", "type": "string", "example": "marked today" } } }, "assignee": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "follower": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "old_section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, "new_section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, "task": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "tag": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "custom_field": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, "old_text_value": { "description": "*Conditional* The previous value of a text-type field before it was updated.", "type": "string", "readOnly": true, "example": "This was the old text" }, "new_text_value": { "description": "*Conditional* The new value of a text-type field after it was updated.", "type": "string", "readOnly": true, "example": "This is the new text" }, "old_number_value": { "description": "*Conditional* The previous value of a number-type custom field before the update.", "type": "integer", "nullable": true, "readOnly": true, "example": 1 }, "new_number_value": { "description": "*Conditional* The new value of a number-type custom field after the update.", "type": "integer", "readOnly": true, "example": 2 }, "old_enum_value": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "new_enum_value": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "old_date_value": { "allOf": [ { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, { "description": "*Conditional*. The old value of a date custom field story." } ], "readOnly": true }, "new_date_value": { "allOf": [ { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, { "description": "*Conditional* The new value of a date custom field story." } ], "readOnly": true }, "old_people_value": { "description": "*Conditional*. The old value of a people custom field story.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "new_people_value": { "description": "*Conditional*. The new value of a people custom field story.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "old_multi_enum_values": { "description": "*Conditional*. The old value of a multi-enum custom field story.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "readOnly": true }, "new_multi_enum_values": { "description": "*Conditional*. The new value of a multi-enum custom field story.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "readOnly": true }, "new_approval_status": { "description": "*Conditional*. The new value of approval status.", "type": "string", "readOnly": true, "example": "approved" }, "old_approval_status": { "description": "*Conditional*. The old value of approval status.", "type": "string", "readOnly": true, "example": "pending" }, "duplicate_of": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "duplicated_from": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "dependency": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "source": { "description": "The component of the Asana product the user used to trigger the story.", "type": "string", "enum": [ "web", "email", "mobile", "api", "unknown" ], "readOnly": true, "example": "web" }, "target": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "readOnly": true, "description": "The object this story is associated with. Currently may only be a task." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "stories:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nStory result = client.stories.getStory(storyGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet storiesApiInstance = new Asana.StoriesApi();\nlet story_gid = \"35678\"; // String | Globally unique identifier for the story.\nlet opts = { \n 'opt_fields': \"assignee,assignee.name,created_at,created_by,created_by.name,custom_field,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.id_prefix,custom_field.is_formula_field,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.representation_type,custom_field.text_value,custom_field.type,dependency,dependency.created_by,dependency.name,dependency.resource_subtype,duplicate_of,duplicate_of.created_by,duplicate_of.name,duplicate_of.resource_subtype,duplicated_from,duplicated_from.created_by,duplicated_from.name,duplicated_from.resource_subtype,follower,follower.name,hearted,hearts,hearts.user,hearts.user.name,html_text,is_editable,is_edited,is_pinned,liked,likes,likes.user,likes.user.name,new_approval_status,new_date_value,new_dates,new_dates.due_at,new_dates.due_on,new_dates.start_on,new_enum_value,new_enum_value.color,new_enum_value.enabled,new_enum_value.name,new_multi_enum_values,new_multi_enum_values.color,new_multi_enum_values.enabled,new_multi_enum_values.name,new_name,new_number_value,new_people_value,new_people_value.name,new_resource_subtype,new_section,new_section.name,new_text_value,num_hearts,num_likes,old_approval_status,old_date_value,old_dates,old_dates.due_at,old_dates.due_on,old_dates.start_on,old_enum_value,old_enum_value.color,old_enum_value.enabled,old_enum_value.name,old_multi_enum_values,old_multi_enum_values.color,old_multi_enum_values.enabled,old_multi_enum_values.name,old_name,old_number_value,old_people_value,old_people_value.name,old_resource_subtype,old_section,old_section.name,old_text_value,previews,previews.fallback,previews.footer,previews.header,previews.header_link,previews.html_text,previews.text,previews.title,previews.title_link,project,project.name,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,source,sticker_name,story,story.created_at,story.created_by,story.created_by.name,story.resource_subtype,story.text,tag,tag.name,target,target.created_by,target.name,target.resource_subtype,task,task.created_by,task.name,task.resource_subtype,text,type\"\n};\nstoriesApiInstance.getStory(story_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.stories.getStory(storyGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nstories_api_instance = asana.StoriesApi(api_client)\nstory_gid = \"35678\" # str | Globally unique identifier for the story.\nopts = {\n 'opt_fields': \"assignee,assignee.name,created_at,created_by,created_by.name,custom_field,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.id_prefix,custom_field.input_restrictions,custom_field.is_formula_field,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.representation_type,custom_field.text_value,custom_field.type,dependency,dependency.created_by,dependency.name,dependency.resource_subtype,duplicate_of,duplicate_of.created_by,duplicate_of.name,duplicate_of.resource_subtype,duplicated_from,duplicated_from.created_by,duplicated_from.name,duplicated_from.resource_subtype,follower,follower.name,hearted,hearts,hearts.user,hearts.user.name,html_text,is_editable,is_edited,is_pinned,liked,likes,likes.user,likes.user.name,new_approval_status,new_date_value,new_dates,new_dates.due_at,new_dates.due_on,new_dates.start_on,new_enum_value,new_enum_value.color,new_enum_value.enabled,new_enum_value.name,new_multi_enum_values,new_multi_enum_values.color,new_multi_enum_values.enabled,new_multi_enum_values.name,new_name,new_number_value,new_people_value,new_people_value.name,new_resource_subtype,new_section,new_section.name,new_text_value,num_hearts,num_likes,old_approval_status,old_date_value,old_dates,old_dates.due_at,old_dates.due_on,old_dates.start_on,old_enum_value,old_enum_value.color,old_enum_value.enabled,old_enum_value.name,old_multi_enum_values,old_multi_enum_values.color,old_multi_enum_values.enabled,old_multi_enum_values.name,old_name,old_number_value,old_people_value,old_people_value.name,old_resource_subtype,old_section,old_section.name,old_text_value,previews,previews.fallback,previews.footer,previews.header,previews.header_link,previews.html_text,previews.text,previews.title,previews.title_link,project,project.name,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,source,sticker_name,story,story.created_at,story.created_by,story.created_by.name,story.resource_subtype,story.text,tag,tag.name,target,target.created_by,target.name,target.resource_subtype,task,task.created_by,task.name,task.resource_subtype,text,type\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a story\n api_response = stories_api_instance.get_story(story_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling StoriesApi->get_story: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.stories.get_story(story_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "stories->getStory($story_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.stories.get_story(story_gid: 'story_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a story", "description": "Required scope: stories:write\n\nUpdates the story and returns the full record for the updated story. Only comment stories can have their text updated, and only comment stories and attachment stories can be pinned. Only one of `text` and `html_text` can be specified.", "tags": [ "Stories" ], "operationId": "updateStory", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "assignee", "assignee.name", "created_at", "created_by", "created_by.name", "custom_field", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.representation_type", "custom_field.text_value", "custom_field.type", "dependency", "dependency.created_by", "dependency.name", "dependency.resource_subtype", "duplicate_of", "duplicate_of.created_by", "duplicate_of.name", "duplicate_of.resource_subtype", "duplicated_from", "duplicated_from.created_by", "duplicated_from.name", "duplicated_from.resource_subtype", "follower", "follower.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "is_editable", "is_edited", "is_pinned", "liked", "likes", "likes.user", "likes.user.name", "new_approval_status", "new_date_value", "new_dates", "new_dates.due_at", "new_dates.due_on", "new_dates.start_on", "new_enum_value", "new_enum_value.color", "new_enum_value.enabled", "new_enum_value.name", "new_multi_enum_values", "new_multi_enum_values.color", "new_multi_enum_values.enabled", "new_multi_enum_values.name", "new_name", "new_number_value", "new_people_value", "new_people_value.name", "new_resource_subtype", "new_section", "new_section.name", "new_text_value", "num_hearts", "num_likes", "old_approval_status", "old_date_value", "old_dates", "old_dates.due_at", "old_dates.due_on", "old_dates.start_on", "old_enum_value", "old_enum_value.color", "old_enum_value.enabled", "old_enum_value.name", "old_multi_enum_values", "old_multi_enum_values.color", "old_multi_enum_values.enabled", "old_multi_enum_values.name", "old_name", "old_number_value", "old_people_value", "old_people_value.name", "old_resource_subtype", "old_section", "old_section.name", "old_text_value", "previews", "previews.fallback", "previews.footer", "previews.header", "previews.header_link", "previews.html_text", "previews.text", "previews.title", "previews.title_link", "project", "project.name", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "source", "sticker_name", "story", "story.created_at", "story.created_by", "story.created_by.name", "story.resource_subtype", "story.text", "tag", "tag.name", "target", "target.created_by", "target.name", "target.resource_subtype", "task", "task.created_by", "task.name", "task.resource_subtype", "text", "type" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "assignee", "assignee.name", "created_at", "created_by", "created_by.name", "custom_field", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.representation_type", "custom_field.text_value", "custom_field.type", "dependency", "dependency.created_by", "dependency.name", "dependency.resource_subtype", "duplicate_of", "duplicate_of.created_by", "duplicate_of.name", "duplicate_of.resource_subtype", "duplicated_from", "duplicated_from.created_by", "duplicated_from.name", "duplicated_from.resource_subtype", "follower", "follower.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "is_editable", "is_edited", "is_pinned", "liked", "likes", "likes.user", "likes.user.name", "new_approval_status", "new_date_value", "new_dates", "new_dates.due_at", "new_dates.due_on", "new_dates.start_on", "new_enum_value", "new_enum_value.color", "new_enum_value.enabled", "new_enum_value.name", "new_multi_enum_values", "new_multi_enum_values.color", "new_multi_enum_values.enabled", "new_multi_enum_values.name", "new_name", "new_number_value", "new_people_value", "new_people_value.name", "new_resource_subtype", "new_section", "new_section.name", "new_text_value", "num_hearts", "num_likes", "old_approval_status", "old_date_value", "old_dates", "old_dates.due_at", "old_dates.due_on", "old_dates.start_on", "old_enum_value", "old_enum_value.color", "old_enum_value.enabled", "old_enum_value.name", "old_multi_enum_values", "old_multi_enum_values.color", "old_multi_enum_values.enabled", "old_multi_enum_values.name", "old_name", "old_number_value", "old_people_value", "old_people_value.name", "old_resource_subtype", "old_section", "old_section.name", "old_text_value", "previews", "previews.fallback", "previews.footer", "previews.header", "previews.header_link", "previews.html_text", "previews.text", "previews.title", "previews.title_link", "project", "project.name", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "source", "sticker_name", "story", "story.created_at", "story.created_by", "story.created_by.name", "story.resource_subtype", "story.text", "tag", "tag.name", "target", "target.created_by", "target.name", "target.resource_subtype", "task", "task.created_by", "task.name", "task.resource_subtype", "text", "type" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The comment story to update.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A story represents an activity associated with an object in the Asana system.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "story", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "comment_added" }, "text": { "description": "The plain text of the comment to add. Cannot be used with html_text.", "type": "string", "example": "This is a comment." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). HTML formatted text for a comment. This will not include the name of the creator.", "type": "string", "example": "This is a comment." }, "is_pinned": { "description": "*Conditional*. Whether the story should be pinned on the resource.", "type": "boolean", "example": false }, "sticker_name": { "description": "The name of the sticker in this story. `null` if there is no sticker.", "type": "string", "enum": [ "green_checkmark", "people_dancing", "dancing_unicorn", "heart", "party_popper", "people_waving_flags", "splashing_narwhal", "trophy", "yeti_riding_unicorn", "celebrating_people", "determined_climbers", "phoenix_spreading_love" ], "example": "dancing_unicorn" } } } } } } } }, "responses": { "200": { "description": "Successfully retrieved the specified story.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A story represents an activity associated with an object in the Asana system.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "story", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "comment_added" }, "text": { "description": "The plain text of the comment to add. Cannot be used with html_text.", "type": "string", "example": "This is a comment." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). HTML formatted text for a comment. This will not include the name of the creator.", "type": "string", "example": "This is a comment." }, "is_pinned": { "description": "*Conditional*. Whether the story should be pinned on the resource.", "type": "boolean", "example": false }, "sticker_name": { "description": "The name of the sticker in this story. `null` if there is no sticker.", "type": "string", "enum": [ "green_checkmark", "people_dancing", "dancing_unicorn", "heart", "party_popper", "people_waving_flags", "splashing_narwhal", "trophy", "yeti_riding_unicorn", "celebrating_people", "determined_climbers", "phoenix_spreading_love" ], "example": "dancing_unicorn" } } }, { "type": "object", "properties": { "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "type": { "type": "string", "enum": [ "comment", "system" ], "readOnly": true, "example": "comment" }, "is_editable": { "description": "*Conditional*. Whether the text of the story can be edited after creation.", "type": "boolean", "readOnly": true, "example": false }, "is_edited": { "description": "*Conditional*. Whether the text of the story has been edited after creation.", "type": "boolean", "readOnly": true, "example": false }, "hearted": { "description": "*Deprecated - please use likes instead*\n*Conditional*. True if the story is hearted by the authorized user, false if not.", "type": "boolean", "readOnly": true, "example": false }, "hearts": { "description": "*Deprecated - please use likes instead*\n\n*Conditional*. Array of likes for users who have hearted this story.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_hearts": { "description": "*Deprecated - please use likes instead*\n\n*Conditional*. The number of users who have hearted this story.", "type": "integer", "readOnly": true, "example": 5 }, "liked": { "description": "*Conditional*. True if the story is liked by the authorized user, false if not.", "type": "boolean", "readOnly": true, "example": false }, "likes": { "description": "*Conditional*. Array of likes for users who have liked this story.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_likes": { "description": "*Conditional*. The number of users who have liked this story.", "type": "integer", "readOnly": true, "example": 5 }, "reaction_summary": { "description": "Summary of emoji reactions on this story.", "type": "array", "items": { "type": "object", "description": "A summary of an emoji reaction on an object.", "properties": { "emoji_base": { "description": "The emoji base character used in the reaction.", "type": "string", "example": "\ud83d\udc4e" }, "variant": { "description": "The full emoji string used in the reaction.", "type": "string", "example": "\ud83d\udc4e\ud83c\udffc" }, "count": { "description": "The number of reactions with the emoji variant on the object.", "type": "number", "example": 1 }, "reacted": { "description": "Whether the current user has reacted with the emoji variant on the object.", "type": "boolean", "example": false } } }, "readOnly": true }, "previews": { "description": "

Full object requires scope: attachments:read

\n\n*Conditional*. A collection of previews to be displayed in the story.\n\n*Note: This property only exists for comment stories.*", "type": "array", "items": { "type": "object", "description": "A collection of rich text that will be displayed as a preview to another app.\n\nThis is read-only except for a small group of whitelisted apps.", "readOnly": true, "properties": { "fallback": { "description": "Some fallback text to display if unable to display the full preview.", "type": "string", "example": "Greg: Great! I like this idea.\\n\\nhttps//a_company.slack.com/archives/ABCDEFG/12345678" }, "footer": { "description": "Text to display in the footer.", "type": "string", "example": "Mar 17, 2019 1:25 PM" }, "header": { "description": "Text to display in the header.", "type": "string", "example": "Asana for Slack" }, "header_link": { "description": "Where the header will link to.", "type": "string", "example": "https://asana.comn/apps/slack" }, "html_text": { "description": "HTML formatted text for the body of the preview.", "type": "string", "example": "Great! I like this idea." }, "text": { "description": "Text for the body of the preview.", "type": "string", "example": "Great! I like this idea." }, "title": { "description": "Text to display as the title.", "type": "string", "example": "Greg" }, "title_link": { "description": "Where to title will link to.", "type": "string", "example": "https://asana.slack.com/archives/ABCDEFG/12345678" } } }, "readOnly": true }, "old_name": { "description": "*Conditional* The previous name of the task before a name change.", "type": "string", "example": "This was the old name" }, "new_name": { "description": "*Conditional* The updated name of the task after a name change.", "type": "string", "nullable": true, "readOnly": true, "example": "This is the new name" }, "old_dates": { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, "new_dates": { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, "old_resource_subtype": { "description": "*Conditional*", "type": "string", "readOnly": true, "example": "default_task" }, "new_resource_subtype": { "description": "*Conditional*", "type": "string", "readOnly": true, "example": "milestone" }, "story": { "description": "A story represents an activity associated with an object in the Asana system.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "story", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "comment_added" }, "text": { "description": "*Create-only*. Human-readable text for the story or comment.\nThis will not include the name of the creator.\n*Note: This is not guaranteed to be stable for a given type of story. For example, text for a reassignment may not always say \u201cassigned to \u2026\u201d as the text for a story can both be edited and change based on the language settings of the user making the request.*\nUse the `resource_subtype` property to discover the action that created the story.", "type": "string", "example": "marked today" } } }, "assignee": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "follower": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "old_section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, "new_section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, "task": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "tag": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "custom_field": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, "old_text_value": { "description": "*Conditional* The previous value of a text-type field before it was updated.", "type": "string", "readOnly": true, "example": "This was the old text" }, "new_text_value": { "description": "*Conditional* The new value of a text-type field after it was updated.", "type": "string", "readOnly": true, "example": "This is the new text" }, "old_number_value": { "description": "*Conditional* The previous value of a number-type custom field before the update.", "type": "integer", "nullable": true, "readOnly": true, "example": 1 }, "new_number_value": { "description": "*Conditional* The new value of a number-type custom field after the update.", "type": "integer", "readOnly": true, "example": 2 }, "old_enum_value": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "new_enum_value": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "old_date_value": { "allOf": [ { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, { "description": "*Conditional*. The old value of a date custom field story." } ], "readOnly": true }, "new_date_value": { "allOf": [ { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, { "description": "*Conditional* The new value of a date custom field story." } ], "readOnly": true }, "old_people_value": { "description": "*Conditional*. The old value of a people custom field story.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "new_people_value": { "description": "*Conditional*. The new value of a people custom field story.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "old_multi_enum_values": { "description": "*Conditional*. The old value of a multi-enum custom field story.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "readOnly": true }, "new_multi_enum_values": { "description": "*Conditional*. The new value of a multi-enum custom field story.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "readOnly": true }, "new_approval_status": { "description": "*Conditional*. The new value of approval status.", "type": "string", "readOnly": true, "example": "approved" }, "old_approval_status": { "description": "*Conditional*. The old value of approval status.", "type": "string", "readOnly": true, "example": "pending" }, "duplicate_of": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "duplicated_from": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "dependency": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "source": { "description": "The component of the Asana product the user used to trigger the story.", "type": "string", "enum": [ "web", "email", "mobile", "api", "unknown" ], "readOnly": true, "example": "web" }, "target": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "readOnly": true, "description": "The object this story is associated with. Currently may only be a task." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "stories:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nStory result = client.stories.updateStory(storyGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet storiesApiInstance = new Asana.StoriesApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The comment story to update.\nlet story_gid = \"35678\"; // String | Globally unique identifier for the story.\nlet opts = { \n 'opt_fields': \"assignee,assignee.name,created_at,created_by,created_by.name,custom_field,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.id_prefix,custom_field.is_formula_field,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.representation_type,custom_field.text_value,custom_field.type,dependency,dependency.created_by,dependency.name,dependency.resource_subtype,duplicate_of,duplicate_of.created_by,duplicate_of.name,duplicate_of.resource_subtype,duplicated_from,duplicated_from.created_by,duplicated_from.name,duplicated_from.resource_subtype,follower,follower.name,hearted,hearts,hearts.user,hearts.user.name,html_text,is_editable,is_edited,is_pinned,liked,likes,likes.user,likes.user.name,new_approval_status,new_date_value,new_dates,new_dates.due_at,new_dates.due_on,new_dates.start_on,new_enum_value,new_enum_value.color,new_enum_value.enabled,new_enum_value.name,new_multi_enum_values,new_multi_enum_values.color,new_multi_enum_values.enabled,new_multi_enum_values.name,new_name,new_number_value,new_people_value,new_people_value.name,new_resource_subtype,new_section,new_section.name,new_text_value,num_hearts,num_likes,old_approval_status,old_date_value,old_dates,old_dates.due_at,old_dates.due_on,old_dates.start_on,old_enum_value,old_enum_value.color,old_enum_value.enabled,old_enum_value.name,old_multi_enum_values,old_multi_enum_values.color,old_multi_enum_values.enabled,old_multi_enum_values.name,old_name,old_number_value,old_people_value,old_people_value.name,old_resource_subtype,old_section,old_section.name,old_text_value,previews,previews.fallback,previews.footer,previews.header,previews.header_link,previews.html_text,previews.text,previews.title,previews.title_link,project,project.name,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,source,sticker_name,story,story.created_at,story.created_by,story.created_by.name,story.resource_subtype,story.text,tag,tag.name,target,target.created_by,target.name,target.resource_subtype,task,task.created_by,task.name,task.resource_subtype,text,type\"\n};\nstoriesApiInstance.updateStory(body, story_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.stories.updateStory(storyGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nstories_api_instance = asana.StoriesApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The comment story to update.\nstory_gid = \"35678\" # str | Globally unique identifier for the story.\nopts = {\n 'opt_fields': \"assignee,assignee.name,created_at,created_by,created_by.name,custom_field,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.id_prefix,custom_field.input_restrictions,custom_field.is_formula_field,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.representation_type,custom_field.text_value,custom_field.type,dependency,dependency.created_by,dependency.name,dependency.resource_subtype,duplicate_of,duplicate_of.created_by,duplicate_of.name,duplicate_of.resource_subtype,duplicated_from,duplicated_from.created_by,duplicated_from.name,duplicated_from.resource_subtype,follower,follower.name,hearted,hearts,hearts.user,hearts.user.name,html_text,is_editable,is_edited,is_pinned,liked,likes,likes.user,likes.user.name,new_approval_status,new_date_value,new_dates,new_dates.due_at,new_dates.due_on,new_dates.start_on,new_enum_value,new_enum_value.color,new_enum_value.enabled,new_enum_value.name,new_multi_enum_values,new_multi_enum_values.color,new_multi_enum_values.enabled,new_multi_enum_values.name,new_name,new_number_value,new_people_value,new_people_value.name,new_resource_subtype,new_section,new_section.name,new_text_value,num_hearts,num_likes,old_approval_status,old_date_value,old_dates,old_dates.due_at,old_dates.due_on,old_dates.start_on,old_enum_value,old_enum_value.color,old_enum_value.enabled,old_enum_value.name,old_multi_enum_values,old_multi_enum_values.color,old_multi_enum_values.enabled,old_multi_enum_values.name,old_name,old_number_value,old_people_value,old_people_value.name,old_resource_subtype,old_section,old_section.name,old_text_value,previews,previews.fallback,previews.footer,previews.header,previews.header_link,previews.html_text,previews.text,previews.title,previews.title_link,project,project.name,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,source,sticker_name,story,story.created_at,story.created_by,story.created_by.name,story.resource_subtype,story.text,tag,tag.name,target,target.created_by,target.name,target.resource_subtype,task,task.created_by,task.name,task.resource_subtype,text,type\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a story\n api_response = stories_api_instance.update_story(body, story_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling StoriesApi->update_story: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.stories.update_story(story_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "stories->updateStory($story_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.stories.update_story(story_gid: 'story_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 8, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a story", "description": "Deletes a story. A user can only delete stories they have created.\n\nReturns an empty data record.", "tags": [ "Stories" ], "operationId": "deleteStory", "responses": { "200": { "description": "Successfully deleted the specified story.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.stories.deleteStory(storyGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet storiesApiInstance = new Asana.StoriesApi();\nlet story_gid = \"35678\"; // String | Globally unique identifier for the story.\n\nstoriesApiInstance.deleteStory(story_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.stories.deleteStory(storyGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nstories_api_instance = asana.StoriesApi(api_client)\nstory_gid = \"35678\" # str | Globally unique identifier for the story.\n\n\ntry:\n # Delete a story\n api_response = stories_api_instance.delete_story(story_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling StoriesApi->delete_story: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.stories.delete_story(story_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "stories->deleteStory($story_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.stories.delete_story(story_gid: 'story_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/stories": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get stories from a task", "description": "Required scope: stories:read\n\nReturns the compact records for all stories on the task.", "tags": [ "Stories" ], "operationId": "getStoriesForTask", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "assignee", "assignee.name", "created_at", "created_by", "created_by.name", "custom_field", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.representation_type", "custom_field.text_value", "custom_field.type", "dependency", "dependency.created_by", "dependency.name", "dependency.resource_subtype", "duplicate_of", "duplicate_of.created_by", "duplicate_of.name", "duplicate_of.resource_subtype", "duplicated_from", "duplicated_from.created_by", "duplicated_from.name", "duplicated_from.resource_subtype", "follower", "follower.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "is_editable", "is_edited", "is_pinned", "liked", "likes", "likes.user", "likes.user.name", "new_approval_status", "new_date_value", "new_dates", "new_dates.due_at", "new_dates.due_on", "new_dates.start_on", "new_enum_value", "new_enum_value.color", "new_enum_value.enabled", "new_enum_value.name", "new_multi_enum_values", "new_multi_enum_values.color", "new_multi_enum_values.enabled", "new_multi_enum_values.name", "new_name", "new_number_value", "new_people_value", "new_people_value.name", "new_resource_subtype", "new_section", "new_section.name", "new_text_value", "num_hearts", "num_likes", "offset", "old_approval_status", "old_date_value", "old_dates", "old_dates.due_at", "old_dates.due_on", "old_dates.start_on", "old_enum_value", "old_enum_value.color", "old_enum_value.enabled", "old_enum_value.name", "old_multi_enum_values", "old_multi_enum_values.color", "old_multi_enum_values.enabled", "old_multi_enum_values.name", "old_name", "old_number_value", "old_people_value", "old_people_value.name", "old_resource_subtype", "old_section", "old_section.name", "old_text_value", "path", "previews", "previews.fallback", "previews.footer", "previews.header", "previews.header_link", "previews.html_text", "previews.text", "previews.title", "previews.title_link", "project", "project.name", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "source", "sticker_name", "story", "story.created_at", "story.created_by", "story.created_by.name", "story.resource_subtype", "story.text", "tag", "tag.name", "target", "target.created_by", "target.name", "target.resource_subtype", "task", "task.created_by", "task.name", "task.resource_subtype", "text", "type", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "assignee", "assignee.name", "created_at", "created_by", "created_by.name", "custom_field", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.representation_type", "custom_field.text_value", "custom_field.type", "dependency", "dependency.created_by", "dependency.name", "dependency.resource_subtype", "duplicate_of", "duplicate_of.created_by", "duplicate_of.name", "duplicate_of.resource_subtype", "duplicated_from", "duplicated_from.created_by", "duplicated_from.name", "duplicated_from.resource_subtype", "follower", "follower.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "is_editable", "is_edited", "is_pinned", "liked", "likes", "likes.user", "likes.user.name", "new_approval_status", "new_date_value", "new_dates", "new_dates.due_at", "new_dates.due_on", "new_dates.start_on", "new_enum_value", "new_enum_value.color", "new_enum_value.enabled", "new_enum_value.name", "new_multi_enum_values", "new_multi_enum_values.color", "new_multi_enum_values.enabled", "new_multi_enum_values.name", "new_name", "new_number_value", "new_people_value", "new_people_value.name", "new_resource_subtype", "new_section", "new_section.name", "new_text_value", "num_hearts", "num_likes", "offset", "old_approval_status", "old_date_value", "old_dates", "old_dates.due_at", "old_dates.due_on", "old_dates.start_on", "old_enum_value", "old_enum_value.color", "old_enum_value.enabled", "old_enum_value.name", "old_multi_enum_values", "old_multi_enum_values.color", "old_multi_enum_values.enabled", "old_multi_enum_values.name", "old_name", "old_number_value", "old_people_value", "old_people_value.name", "old_resource_subtype", "old_section", "old_section.name", "old_text_value", "path", "previews", "previews.fallback", "previews.footer", "previews.header", "previews.header_link", "previews.html_text", "previews.text", "previews.title", "previews.title_link", "project", "project.name", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "source", "sticker_name", "story", "story.created_at", "story.created_by", "story.created_by.name", "story.resource_subtype", "story.text", "tag", "tag.name", "target", "target.created_by", "target.name", "target.resource_subtype", "task", "task.created_by", "task.name", "task.resource_subtype", "text", "type", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified task's stories.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A story represents an activity associated with an object in the Asana system.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "story", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "comment_added" }, "text": { "description": "*Create-only*. Human-readable text for the story or comment.\nThis will not include the name of the creator.\n*Note: This is not guaranteed to be stable for a given type of story. For example, text for a reassignment may not always say \u201cassigned to \u2026\u201d as the text for a story can both be edited and change based on the language settings of the user making the request.*\nUse the `resource_subtype` property to discover the action that created the story.", "type": "string", "example": "marked today" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "stories:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.stories.getStoriesForTask(taskGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet storiesApiInstance = new Asana.StoriesApi();\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"assignee,assignee.name,created_at,created_by,created_by.name,custom_field,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.id_prefix,custom_field.is_formula_field,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.representation_type,custom_field.text_value,custom_field.type,dependency,dependency.created_by,dependency.name,dependency.resource_subtype,duplicate_of,duplicate_of.created_by,duplicate_of.name,duplicate_of.resource_subtype,duplicated_from,duplicated_from.created_by,duplicated_from.name,duplicated_from.resource_subtype,follower,follower.name,hearted,hearts,hearts.user,hearts.user.name,html_text,is_editable,is_edited,is_pinned,liked,likes,likes.user,likes.user.name,new_approval_status,new_date_value,new_dates,new_dates.due_at,new_dates.due_on,new_dates.start_on,new_enum_value,new_enum_value.color,new_enum_value.enabled,new_enum_value.name,new_multi_enum_values,new_multi_enum_values.color,new_multi_enum_values.enabled,new_multi_enum_values.name,new_name,new_number_value,new_people_value,new_people_value.name,new_resource_subtype,new_section,new_section.name,new_text_value,num_hearts,num_likes,offset,old_approval_status,old_date_value,old_dates,old_dates.due_at,old_dates.due_on,old_dates.start_on,old_enum_value,old_enum_value.color,old_enum_value.enabled,old_enum_value.name,old_multi_enum_values,old_multi_enum_values.color,old_multi_enum_values.enabled,old_multi_enum_values.name,old_name,old_number_value,old_people_value,old_people_value.name,old_resource_subtype,old_section,old_section.name,old_text_value,path,previews,previews.fallback,previews.footer,previews.header,previews.header_link,previews.html_text,previews.text,previews.title,previews.title_link,project,project.name,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,source,sticker_name,story,story.created_at,story.created_by,story.created_by.name,story.resource_subtype,story.text,tag,tag.name,target,target.created_by,target.name,target.resource_subtype,task,task.created_by,task.name,task.resource_subtype,text,type,uri\"\n};\nstoriesApiInstance.getStoriesForTask(task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.stories.getStoriesForTask(taskGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nstories_api_instance = asana.StoriesApi(api_client)\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"assignee,assignee.name,created_at,created_by,created_by.name,custom_field,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.id_prefix,custom_field.input_restrictions,custom_field.is_formula_field,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.representation_type,custom_field.text_value,custom_field.type,dependency,dependency.created_by,dependency.name,dependency.resource_subtype,duplicate_of,duplicate_of.created_by,duplicate_of.name,duplicate_of.resource_subtype,duplicated_from,duplicated_from.created_by,duplicated_from.name,duplicated_from.resource_subtype,follower,follower.name,hearted,hearts,hearts.user,hearts.user.name,html_text,is_editable,is_edited,is_pinned,liked,likes,likes.user,likes.user.name,new_approval_status,new_date_value,new_dates,new_dates.due_at,new_dates.due_on,new_dates.start_on,new_enum_value,new_enum_value.color,new_enum_value.enabled,new_enum_value.name,new_multi_enum_values,new_multi_enum_values.color,new_multi_enum_values.enabled,new_multi_enum_values.name,new_name,new_number_value,new_people_value,new_people_value.name,new_resource_subtype,new_section,new_section.name,new_text_value,num_hearts,num_likes,offset,old_approval_status,old_date_value,old_dates,old_dates.due_at,old_dates.due_on,old_dates.start_on,old_enum_value,old_enum_value.color,old_enum_value.enabled,old_enum_value.name,old_multi_enum_values,old_multi_enum_values.color,old_multi_enum_values.enabled,old_multi_enum_values.name,old_name,old_number_value,old_people_value,old_people_value.name,old_resource_subtype,old_section,old_section.name,old_text_value,path,previews,previews.fallback,previews.footer,previews.header,previews.header_link,previews.html_text,previews.text,previews.title,previews.title_link,project,project.name,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,source,sticker_name,story,story.created_at,story.created_by,story.created_by.name,story.resource_subtype,story.text,tag,tag.name,target,target.created_by,target.name,target.resource_subtype,task,task.created_by,task.name,task.resource_subtype,text,type,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get stories from a task\n api_response = stories_api_instance.get_stories_for_task(task_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling StoriesApi->get_stories_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.stories.get_stories_for_task(task_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "stories->getStoriesForTask($task_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.stories.get_stories_for_task(task_gid: 'task_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a story on a task", "description": "Required scope: stories:write\n\nAdds a story to a task. This endpoint currently only allows for comment\nstories to be created. The comment will be authored by the currently\nauthenticated user, and timestamped when the server receives the request.\n\nReturns the full record for the new story added to the task.", "tags": [ "Stories" ], "operationId": "createStoryForTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "assignee", "assignee.name", "created_at", "created_by", "created_by.name", "custom_field", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.representation_type", "custom_field.text_value", "custom_field.type", "dependency", "dependency.created_by", "dependency.name", "dependency.resource_subtype", "duplicate_of", "duplicate_of.created_by", "duplicate_of.name", "duplicate_of.resource_subtype", "duplicated_from", "duplicated_from.created_by", "duplicated_from.name", "duplicated_from.resource_subtype", "follower", "follower.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "is_editable", "is_edited", "is_pinned", "liked", "likes", "likes.user", "likes.user.name", "new_approval_status", "new_date_value", "new_dates", "new_dates.due_at", "new_dates.due_on", "new_dates.start_on", "new_enum_value", "new_enum_value.color", "new_enum_value.enabled", "new_enum_value.name", "new_multi_enum_values", "new_multi_enum_values.color", "new_multi_enum_values.enabled", "new_multi_enum_values.name", "new_name", "new_number_value", "new_people_value", "new_people_value.name", "new_resource_subtype", "new_section", "new_section.name", "new_text_value", "num_hearts", "num_likes", "old_approval_status", "old_date_value", "old_dates", "old_dates.due_at", "old_dates.due_on", "old_dates.start_on", "old_enum_value", "old_enum_value.color", "old_enum_value.enabled", "old_enum_value.name", "old_multi_enum_values", "old_multi_enum_values.color", "old_multi_enum_values.enabled", "old_multi_enum_values.name", "old_name", "old_number_value", "old_people_value", "old_people_value.name", "old_resource_subtype", "old_section", "old_section.name", "old_text_value", "previews", "previews.fallback", "previews.footer", "previews.header", "previews.header_link", "previews.html_text", "previews.text", "previews.title", "previews.title_link", "project", "project.name", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "source", "sticker_name", "story", "story.created_at", "story.created_by", "story.created_by.name", "story.resource_subtype", "story.text", "tag", "tag.name", "target", "target.created_by", "target.name", "target.resource_subtype", "task", "task.created_by", "task.name", "task.resource_subtype", "text", "type" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "assignee", "assignee.name", "created_at", "created_by", "created_by.name", "custom_field", "custom_field.date_value", "custom_field.date_value.date", "custom_field.date_value.date_time", "custom_field.display_value", "custom_field.enabled", "custom_field.enum_options", "custom_field.enum_options.color", "custom_field.enum_options.enabled", "custom_field.enum_options.name", "custom_field.enum_value", "custom_field.enum_value.color", "custom_field.enum_value.enabled", "custom_field.enum_value.name", "custom_field.id_prefix", "custom_field.input_restrictions", "custom_field.is_formula_field", "custom_field.multi_enum_values", "custom_field.multi_enum_values.color", "custom_field.multi_enum_values.enabled", "custom_field.multi_enum_values.name", "custom_field.name", "custom_field.number_value", "custom_field.representation_type", "custom_field.text_value", "custom_field.type", "dependency", "dependency.created_by", "dependency.name", "dependency.resource_subtype", "duplicate_of", "duplicate_of.created_by", "duplicate_of.name", "duplicate_of.resource_subtype", "duplicated_from", "duplicated_from.created_by", "duplicated_from.name", "duplicated_from.resource_subtype", "follower", "follower.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_text", "is_editable", "is_edited", "is_pinned", "liked", "likes", "likes.user", "likes.user.name", "new_approval_status", "new_date_value", "new_dates", "new_dates.due_at", "new_dates.due_on", "new_dates.start_on", "new_enum_value", "new_enum_value.color", "new_enum_value.enabled", "new_enum_value.name", "new_multi_enum_values", "new_multi_enum_values.color", "new_multi_enum_values.enabled", "new_multi_enum_values.name", "new_name", "new_number_value", "new_people_value", "new_people_value.name", "new_resource_subtype", "new_section", "new_section.name", "new_text_value", "num_hearts", "num_likes", "old_approval_status", "old_date_value", "old_dates", "old_dates.due_at", "old_dates.due_on", "old_dates.start_on", "old_enum_value", "old_enum_value.color", "old_enum_value.enabled", "old_enum_value.name", "old_multi_enum_values", "old_multi_enum_values.color", "old_multi_enum_values.enabled", "old_multi_enum_values.name", "old_name", "old_number_value", "old_people_value", "old_people_value.name", "old_resource_subtype", "old_section", "old_section.name", "old_text_value", "previews", "previews.fallback", "previews.footer", "previews.header", "previews.header_link", "previews.html_text", "previews.text", "previews.title", "previews.title_link", "project", "project.name", "reaction_summary", "reaction_summary.count", "reaction_summary.emoji_base", "reaction_summary.reacted", "reaction_summary.variant", "resource_subtype", "source", "sticker_name", "story", "story.created_at", "story.created_by", "story.created_by.name", "story.resource_subtype", "story.text", "tag", "tag.name", "target", "target.created_by", "target.name", "target.resource_subtype", "task", "task.created_by", "task.name", "task.resource_subtype", "text", "type" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The story to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A story represents an activity associated with an object in the Asana system.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "story", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "comment_added" }, "text": { "description": "The plain text of the comment to add. Cannot be used with html_text.", "type": "string", "example": "This is a comment." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). HTML formatted text for a comment. This will not include the name of the creator.", "type": "string", "example": "This is a comment." }, "is_pinned": { "description": "*Conditional*. Whether the story should be pinned on the resource.", "type": "boolean", "example": false }, "sticker_name": { "description": "The name of the sticker in this story. `null` if there is no sticker.", "type": "string", "enum": [ "green_checkmark", "people_dancing", "dancing_unicorn", "heart", "party_popper", "people_waving_flags", "splashing_narwhal", "trophy", "yeti_riding_unicorn", "celebrating_people", "determined_climbers", "phoenix_spreading_love" ], "example": "dancing_unicorn" } } } } } } } }, "responses": { "201": { "description": "Successfully created a new story.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A story represents an activity associated with an object in the Asana system.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "story", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "comment_added" }, "text": { "description": "The plain text of the comment to add. Cannot be used with html_text.", "type": "string", "example": "This is a comment." }, "html_text": { "description": "[Opt In](/docs/inputoutput-options). HTML formatted text for a comment. This will not include the name of the creator.", "type": "string", "example": "This is a comment." }, "is_pinned": { "description": "*Conditional*. Whether the story should be pinned on the resource.", "type": "boolean", "example": false }, "sticker_name": { "description": "The name of the sticker in this story. `null` if there is no sticker.", "type": "string", "enum": [ "green_checkmark", "people_dancing", "dancing_unicorn", "heart", "party_popper", "people_waving_flags", "splashing_narwhal", "trophy", "yeti_riding_unicorn", "celebrating_people", "determined_climbers", "phoenix_spreading_love" ], "example": "dancing_unicorn" } } }, { "type": "object", "properties": { "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "type": { "type": "string", "enum": [ "comment", "system" ], "readOnly": true, "example": "comment" }, "is_editable": { "description": "*Conditional*. Whether the text of the story can be edited after creation.", "type": "boolean", "readOnly": true, "example": false }, "is_edited": { "description": "*Conditional*. Whether the text of the story has been edited after creation.", "type": "boolean", "readOnly": true, "example": false }, "hearted": { "description": "*Deprecated - please use likes instead*\n*Conditional*. True if the story is hearted by the authorized user, false if not.", "type": "boolean", "readOnly": true, "example": false }, "hearts": { "description": "*Deprecated - please use likes instead*\n\n*Conditional*. Array of likes for users who have hearted this story.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_hearts": { "description": "*Deprecated - please use likes instead*\n\n*Conditional*. The number of users who have hearted this story.", "type": "integer", "readOnly": true, "example": 5 }, "liked": { "description": "*Conditional*. True if the story is liked by the authorized user, false if not.", "type": "boolean", "readOnly": true, "example": false }, "likes": { "description": "*Conditional*. Array of likes for users who have liked this story.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "num_likes": { "description": "*Conditional*. The number of users who have liked this story.", "type": "integer", "readOnly": true, "example": 5 }, "reaction_summary": { "description": "Summary of emoji reactions on this story.", "type": "array", "items": { "type": "object", "description": "A summary of an emoji reaction on an object.", "properties": { "emoji_base": { "description": "The emoji base character used in the reaction.", "type": "string", "example": "\ud83d\udc4e" }, "variant": { "description": "The full emoji string used in the reaction.", "type": "string", "example": "\ud83d\udc4e\ud83c\udffc" }, "count": { "description": "The number of reactions with the emoji variant on the object.", "type": "number", "example": 1 }, "reacted": { "description": "Whether the current user has reacted with the emoji variant on the object.", "type": "boolean", "example": false } } }, "readOnly": true }, "previews": { "description": "

Full object requires scope: attachments:read

\n\n*Conditional*. A collection of previews to be displayed in the story.\n\n*Note: This property only exists for comment stories.*", "type": "array", "items": { "type": "object", "description": "A collection of rich text that will be displayed as a preview to another app.\n\nThis is read-only except for a small group of whitelisted apps.", "readOnly": true, "properties": { "fallback": { "description": "Some fallback text to display if unable to display the full preview.", "type": "string", "example": "Greg: Great! I like this idea.\\n\\nhttps//a_company.slack.com/archives/ABCDEFG/12345678" }, "footer": { "description": "Text to display in the footer.", "type": "string", "example": "Mar 17, 2019 1:25 PM" }, "header": { "description": "Text to display in the header.", "type": "string", "example": "Asana for Slack" }, "header_link": { "description": "Where the header will link to.", "type": "string", "example": "https://asana.comn/apps/slack" }, "html_text": { "description": "HTML formatted text for the body of the preview.", "type": "string", "example": "Great! I like this idea." }, "text": { "description": "Text for the body of the preview.", "type": "string", "example": "Great! I like this idea." }, "title": { "description": "Text to display as the title.", "type": "string", "example": "Greg" }, "title_link": { "description": "Where to title will link to.", "type": "string", "example": "https://asana.slack.com/archives/ABCDEFG/12345678" } } }, "readOnly": true }, "old_name": { "description": "*Conditional* The previous name of the task before a name change.", "type": "string", "example": "This was the old name" }, "new_name": { "description": "*Conditional* The updated name of the task after a name change.", "type": "string", "nullable": true, "readOnly": true, "example": "This is the new name" }, "old_dates": { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, "new_dates": { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, "old_resource_subtype": { "description": "*Conditional*", "type": "string", "readOnly": true, "example": "default_task" }, "new_resource_subtype": { "description": "*Conditional*", "type": "string", "readOnly": true, "example": "milestone" }, "story": { "description": "A story represents an activity associated with an object in the Asana system.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "story", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "comment_added" }, "text": { "description": "*Create-only*. Human-readable text for the story or comment.\nThis will not include the name of the creator.\n*Note: This is not guaranteed to be stable for a given type of story. For example, text for a reassignment may not always say \u201cassigned to \u2026\u201d as the text for a story can both be edited and change based on the language settings of the user making the request.*\nUse the `resource_subtype` property to discover the action that created the story.", "type": "string", "example": "marked today" } } }, "assignee": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "follower": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "old_section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, "new_section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, "task": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "tag": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "custom_field": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, "old_text_value": { "description": "*Conditional* The previous value of a text-type field before it was updated.", "type": "string", "readOnly": true, "example": "This was the old text" }, "new_text_value": { "description": "*Conditional* The new value of a text-type field after it was updated.", "type": "string", "readOnly": true, "example": "This is the new text" }, "old_number_value": { "description": "*Conditional* The previous value of a number-type custom field before the update.", "type": "integer", "nullable": true, "readOnly": true, "example": 1 }, "new_number_value": { "description": "*Conditional* The new value of a number-type custom field after the update.", "type": "integer", "readOnly": true, "example": 2 }, "old_enum_value": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "new_enum_value": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "old_date_value": { "allOf": [ { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, { "description": "*Conditional*. The old value of a date custom field story." } ], "readOnly": true }, "new_date_value": { "allOf": [ { "description": "*Conditional*", "type": "object", "readOnly": true, "properties": { "start_on": { "description": "The day on which work for this goal begins, or null if the goal has no start date. This takes a date with `YYYY-MM-DD` format, and cannot be set unless there is an accompanying due date.", "type": "string", "format": "date", "example": "2019-09-14", "nullable": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.158Z", "nullable": true }, "due_on": { "description": "The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.", "type": "string", "format": "date", "example": "2019-09-15" } } }, { "description": "*Conditional* The new value of a date custom field story." } ], "readOnly": true }, "old_people_value": { "description": "*Conditional*. The old value of a people custom field story.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "new_people_value": { "description": "*Conditional*. The new value of a people custom field story.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "readOnly": true }, "old_multi_enum_values": { "description": "*Conditional*. The old value of a multi-enum custom field story.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "readOnly": true }, "new_multi_enum_values": { "description": "*Conditional*. The new value of a multi-enum custom field story.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, "readOnly": true }, "new_approval_status": { "description": "*Conditional*. The new value of approval status.", "type": "string", "readOnly": true, "example": "approved" }, "old_approval_status": { "description": "*Conditional*. The old value of approval status.", "type": "string", "readOnly": true, "example": "pending" }, "duplicate_of": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "duplicated_from": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "dependency": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "source": { "description": "The component of the Asana product the user used to trigger the story.", "type": "string", "enum": [ "web", "email", "mobile", "api", "unknown" ], "readOnly": true, "example": "web" }, "target": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "readOnly": true, "description": "The object this story is associated with. Currently may only be a task." } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "stories:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nStory result = client.stories.createStoryForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet storiesApiInstance = new Asana.StoriesApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The story to create.\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'opt_fields': \"assignee,assignee.name,created_at,created_by,created_by.name,custom_field,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.id_prefix,custom_field.is_formula_field,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.representation_type,custom_field.text_value,custom_field.type,dependency,dependency.created_by,dependency.name,dependency.resource_subtype,duplicate_of,duplicate_of.created_by,duplicate_of.name,duplicate_of.resource_subtype,duplicated_from,duplicated_from.created_by,duplicated_from.name,duplicated_from.resource_subtype,follower,follower.name,hearted,hearts,hearts.user,hearts.user.name,html_text,is_editable,is_edited,is_pinned,liked,likes,likes.user,likes.user.name,new_approval_status,new_date_value,new_dates,new_dates.due_at,new_dates.due_on,new_dates.start_on,new_enum_value,new_enum_value.color,new_enum_value.enabled,new_enum_value.name,new_multi_enum_values,new_multi_enum_values.color,new_multi_enum_values.enabled,new_multi_enum_values.name,new_name,new_number_value,new_people_value,new_people_value.name,new_resource_subtype,new_section,new_section.name,new_text_value,num_hearts,num_likes,old_approval_status,old_date_value,old_dates,old_dates.due_at,old_dates.due_on,old_dates.start_on,old_enum_value,old_enum_value.color,old_enum_value.enabled,old_enum_value.name,old_multi_enum_values,old_multi_enum_values.color,old_multi_enum_values.enabled,old_multi_enum_values.name,old_name,old_number_value,old_people_value,old_people_value.name,old_resource_subtype,old_section,old_section.name,old_text_value,previews,previews.fallback,previews.footer,previews.header,previews.header_link,previews.html_text,previews.text,previews.title,previews.title_link,project,project.name,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,source,sticker_name,story,story.created_at,story.created_by,story.created_by.name,story.resource_subtype,story.text,tag,tag.name,target,target.created_by,target.name,target.resource_subtype,task,task.created_by,task.name,task.resource_subtype,text,type\"\n};\nstoriesApiInstance.createStoryForTask(body, task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.stories.createStoryForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nstories_api_instance = asana.StoriesApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The story to create.\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'opt_fields': \"assignee,assignee.name,created_at,created_by,created_by.name,custom_field,custom_field.date_value,custom_field.date_value.date,custom_field.date_value.date_time,custom_field.display_value,custom_field.enabled,custom_field.enum_options,custom_field.enum_options.color,custom_field.enum_options.enabled,custom_field.enum_options.name,custom_field.enum_value,custom_field.enum_value.color,custom_field.enum_value.enabled,custom_field.enum_value.name,custom_field.id_prefix,custom_field.input_restrictions,custom_field.is_formula_field,custom_field.multi_enum_values,custom_field.multi_enum_values.color,custom_field.multi_enum_values.enabled,custom_field.multi_enum_values.name,custom_field.name,custom_field.number_value,custom_field.representation_type,custom_field.text_value,custom_field.type,dependency,dependency.created_by,dependency.name,dependency.resource_subtype,duplicate_of,duplicate_of.created_by,duplicate_of.name,duplicate_of.resource_subtype,duplicated_from,duplicated_from.created_by,duplicated_from.name,duplicated_from.resource_subtype,follower,follower.name,hearted,hearts,hearts.user,hearts.user.name,html_text,is_editable,is_edited,is_pinned,liked,likes,likes.user,likes.user.name,new_approval_status,new_date_value,new_dates,new_dates.due_at,new_dates.due_on,new_dates.start_on,new_enum_value,new_enum_value.color,new_enum_value.enabled,new_enum_value.name,new_multi_enum_values,new_multi_enum_values.color,new_multi_enum_values.enabled,new_multi_enum_values.name,new_name,new_number_value,new_people_value,new_people_value.name,new_resource_subtype,new_section,new_section.name,new_text_value,num_hearts,num_likes,old_approval_status,old_date_value,old_dates,old_dates.due_at,old_dates.due_on,old_dates.start_on,old_enum_value,old_enum_value.color,old_enum_value.enabled,old_enum_value.name,old_multi_enum_values,old_multi_enum_values.color,old_multi_enum_values.enabled,old_multi_enum_values.name,old_name,old_number_value,old_people_value,old_people_value.name,old_resource_subtype,old_section,old_section.name,old_text_value,previews,previews.fallback,previews.footer,previews.header,previews.header_link,previews.html_text,previews.text,previews.title,previews.title_link,project,project.name,reaction_summary,reaction_summary.count,reaction_summary.emoji_base,reaction_summary.reacted,reaction_summary.variant,resource_subtype,source,sticker_name,story,story.created_at,story.created_by,story.created_by.name,story.resource_subtype,story.text,tag,tag.name,target,target.created_by,target.name,target.resource_subtype,task,task.created_by,task.name,task.resource_subtype,text,type\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a story on a task\n api_response = stories_api_instance.create_story_for_task(body, task_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling StoriesApi->create_story_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.stories.create_story_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "stories->createStoryForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.stories.create_story_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 8, "x-moar-complexity-skipped": false } }, "/tags": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get multiple tags", "description": "Required scope: tags:read\n\nReturns the compact tag records for some filtered set of tags. Use one or more of the parameters provided to filter the tags returned.", "tags": [ "Tags" ], "operationId": "getTags", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "workspace", "in": "query", "description": "The workspace to filter tags on.", "schema": { "type": "string" }, "example": "1331" }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "created_at", "followers", "followers.name", "name", "notes", "offset", "path", "permalink_url", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "created_at", "followers", "followers.name", "name", "notes", "offset", "path", "permalink_url", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified set of tags.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tags:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.tags.getTags(workspace)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tagsApiInstance = new Asana.TagsApi();\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'workspace': \"1331\", \n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,offset,path,permalink_url,uri,workspace,workspace.name\"\n};\ntagsApiInstance.getTags(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tags.getTags({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntags_api_instance = asana.TagsApi(api_client)\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'workspace': \"1331\", # str | The workspace to filter tags on.\n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,offset,path,permalink_url,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple tags\n api_response = tags_api_instance.get_tags(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TagsApi->get_tags: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tags.get_tags({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tags->getTags(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tags.get_tags(param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a tag", "description": "Required scope: tags:write\n\nCreates a new tag in a workspace or organization.\n\nEvery tag is required to be created in a specific workspace or\norganization, and this cannot be changed once set. Note that you can use\nthe workspace parameter regardless of whether or not it is an\norganization.\n\nReturns the full record of the newly created tag.", "tags": [ "Tags" ], "operationId": "createTag", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "created_at", "followers", "followers.name", "name", "notes", "permalink_url", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "created_at", "followers", "followers.name", "name", "notes", "permalink_url", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The tag to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "color": { "type": "string", "description": "Color of the tag.", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", null ], "example": "light-green" }, "notes": { "description": "Free-form textual information associated with the tag (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." } } } ] }, { "type": "object", "properties": { "followers": { "type": "array", "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "items": { "type": "string" }, "example": [ "12345", "42563" ] }, "workspace": { "type": "string", "x-env-variable": true, "description": "Gid of an object.", "example": "12345" } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created the newly specified tag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "color": { "type": "string", "description": "Color of the tag.", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", null ], "example": "light-green" }, "notes": { "description": "Free-form textual information associated with the tag (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." } } } ] }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "followers": { "description": "Array of users following this tag.", "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "workspace": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tags:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTag result = client.tags.createTag()\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tagsApiInstance = new Asana.TagsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The tag to create.\nlet opts = { \n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,permalink_url,workspace,workspace.name\"\n};\ntagsApiInstance.createTag(body, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tags.createTag({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntags_api_instance = asana.TagsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The tag to create.\nopts = {\n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,permalink_url,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a tag\n api_response = tags_api_instance.create_tag(body, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TagsApi->create_tag: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tags.create_tag({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tags->createTag(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tags.create_tag(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 7, "x-moar-complexity-skipped": false } }, "/tags/{tag_gid}": { "parameters": [ { "name": "tag_gid", "in": "path", "description": "Globally unique identifier for the tag.", "required": true, "schema": { "type": "string" }, "example": "11235", "x-env-variable": "tag" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a tag", "description": "Required scope: tags:read\n\nReturns the complete tag record for a single tag.", "tags": [ "Tags" ], "operationId": "getTag", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "created_at", "followers", "followers.name", "name", "notes", "permalink_url", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "created_at", "followers", "followers.name", "name", "notes", "permalink_url", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified tag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "color": { "type": "string", "description": "Color of the tag.", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", null ], "example": "light-green" }, "notes": { "description": "Free-form textual information associated with the tag (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." } } } ] }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "followers": { "description": "Array of users following this tag.", "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "workspace": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tags:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTag result = client.tags.getTag(tagGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tagsApiInstance = new Asana.TagsApi();\nlet tag_gid = \"11235\"; // String | Globally unique identifier for the tag.\nlet opts = { \n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,permalink_url,workspace,workspace.name\"\n};\ntagsApiInstance.getTag(tag_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tags.getTag(tagGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntags_api_instance = asana.TagsApi(api_client)\ntag_gid = \"11235\" # str | Globally unique identifier for the tag.\nopts = {\n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,permalink_url,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a tag\n api_response = tags_api_instance.get_tag(tag_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TagsApi->get_tag: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tags.get_tag(tag_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tags->getTag($tag_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tags.get_tag(tag_gid: 'tag_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a tag", "description": "Required scope: tags:write\n\nUpdates the properties of a tag. Only the fields provided in the `data`\nblock will be updated; any unspecified fields will remain unchanged.\n\nWhen using this method, it is best to specify only those fields you wish\nto change, or else you may overwrite changes made by another user since\nyou last retrieved the tag.\n\nReturns the complete updated tag record.", "tags": [ "Tags" ], "operationId": "updateTag", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "created_at", "followers", "followers.name", "name", "notes", "permalink_url", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "created_at", "followers", "followers.name", "name", "notes", "permalink_url", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The tag to update.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "color": { "type": "string", "description": "Color of the tag.", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", null ], "example": "light-green" }, "notes": { "description": "Free-form textual information associated with the tag (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." } } } ] } } } } } }, "responses": { "200": { "description": "Successfully updated the specified tag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "color": { "type": "string", "description": "Color of the tag.", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", null ], "example": "light-green" }, "notes": { "description": "Free-form textual information associated with the tag (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." } } } ] }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "followers": { "description": "Array of users following this tag.", "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "workspace": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tags:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTag result = client.tags.updateTag(tagGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tagsApiInstance = new Asana.TagsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The tag to update.\nlet tag_gid = \"11235\"; // String | Globally unique identifier for the tag.\nlet opts = { \n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,permalink_url,workspace,workspace.name\"\n};\ntagsApiInstance.updateTag(body, tag_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tags.updateTag(tagGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntags_api_instance = asana.TagsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The tag to update.\ntag_gid = \"11235\" # str | Globally unique identifier for the tag.\nopts = {\n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,permalink_url,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a tag\n api_response = tags_api_instance.update_tag(body, tag_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TagsApi->update_tag: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tags.update_tag(tag_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tags->updateTag($tag_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tags.update_tag(tag_gid: 'tag_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 5, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a tag", "description": "A specific, existing tag can be deleted by making a DELETE request on\nthe URL for that tag.\n\nReturns an empty data record.", "tags": [ "Tags" ], "operationId": "deleteTag", "responses": { "200": { "description": "Successfully deleted the specified tag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.tags.deleteTag(tagGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tagsApiInstance = new Asana.TagsApi();\nlet tag_gid = \"11235\"; // String | Globally unique identifier for the tag.\n\ntagsApiInstance.deleteTag(tag_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tags.deleteTag(tagGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntags_api_instance = asana.TagsApi(api_client)\ntag_gid = \"11235\" # str | Globally unique identifier for the tag.\n\n\ntry:\n # Delete a tag\n api_response = tags_api_instance.delete_tag(tag_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TagsApi->delete_tag: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tags.delete_tag(tag_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tags->deleteTag($tag_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tags.delete_tag(tag_gid: 'tag_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/tags": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get a task's tags", "description": "Required scope: tags:read\n\nGet a compact representation of all of the tags the task has.", "tags": [ "Tags" ], "operationId": "getTagsForTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "created_at", "followers", "followers.name", "name", "notes", "offset", "path", "permalink_url", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "created_at", "followers", "followers.name", "name", "notes", "offset", "path", "permalink_url", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the tags for the given task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tags:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.tags.getTagsForTask(taskGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tagsApiInstance = new Asana.TagsApi();\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,offset,path,permalink_url,uri,workspace,workspace.name\"\n};\ntagsApiInstance.getTagsForTask(task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tags.getTagsForTask(taskGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntags_api_instance = asana.TagsApi(api_client)\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,offset,path,permalink_url,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a task's tags\n api_response = tags_api_instance.get_tags_for_task(task_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TagsApi->get_tags_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tags.get_tags_for_task(task_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tags->getTagsForTask($task_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tags.get_tags_for_task(task_gid: 'task_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/tags": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get tags in a workspace", "description": "Required scope: tags:read\n\nReturns the compact tag records for some filtered set of tags. Use one or more of the parameters provided to filter the tags returned.", "tags": [ "Tags" ], "operationId": "getTagsForWorkspace", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "created_at", "followers", "followers.name", "name", "notes", "offset", "path", "permalink_url", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "created_at", "followers", "followers.name", "name", "notes", "offset", "path", "permalink_url", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified set of tags.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tags:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.tags.getTagsForWorkspace(workspaceGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tagsApiInstance = new Asana.TagsApi();\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,offset,path,permalink_url,uri,workspace,workspace.name\"\n};\ntagsApiInstance.getTagsForWorkspace(workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tags.getTagsForWorkspace(workspaceGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntags_api_instance = asana.TagsApi(api_client)\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,offset,path,permalink_url,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get tags in a workspace\n api_response = tags_api_instance.get_tags_for_workspace(workspace_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TagsApi->get_tags_for_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tags.get_tags_for_workspace(workspace_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tags->getTagsForWorkspace($workspace_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tags.get_tags_for_workspace(workspace_gid: 'workspace_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a tag in a workspace", "description": "Required scope: tags:write\n\nCreates a new tag in a workspace or organization.\n\nEvery tag is required to be created in a specific workspace or\norganization, and this cannot be changed once set. Note that you can use\nthe workspace parameter regardless of whether or not it is an\norganization.\n\nReturns the full record of the newly created tag.", "tags": [ "Tags" ], "operationId": "createTagForWorkspace", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "color", "created_at", "followers", "followers.name", "name", "notes", "permalink_url", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "color", "created_at", "followers", "followers.name", "name", "notes", "permalink_url", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The tag to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "color": { "type": "string", "description": "Color of the tag.", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", null ], "example": "light-green" }, "notes": { "description": "Free-form textual information associated with the tag (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." } } } ] }, { "type": "object", "properties": { "followers": { "type": "array", "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "items": { "type": "string" }, "example": [ "12345", "42563" ] } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created the newly specified tag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "properties": { "color": { "type": "string", "description": "Color of the tag.", "nullable": true, "enum": [ "dark-pink", "dark-green", "dark-blue", "dark-red", "dark-teal", "dark-brown", "dark-orange", "dark-purple", "dark-warm-gray", "light-pink", "light-green", "light-blue", "light-red", "light-teal", "light-brown", "light-orange", "light-purple", "light-warm-gray", null ], "example": "light-green" }, "notes": { "description": "Free-form textual information associated with the tag (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." } } } ] }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "followers": { "description": "Array of users following this tag.", "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "workspace": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tags:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTag result = client.tags.createTagForWorkspace(workspaceGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tagsApiInstance = new Asana.TagsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The tag to create.\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,permalink_url,workspace,workspace.name\"\n};\ntagsApiInstance.createTagForWorkspace(body, workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tags.createTagForWorkspace(workspaceGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntags_api_instance = asana.TagsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The tag to create.\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'opt_fields': \"color,created_at,followers,followers.name,name,notes,permalink_url,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a tag in a workspace\n api_response = tags_api_instance.create_tag_for_workspace(body, workspace_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TagsApi->create_tag_for_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tags.create_tag_for_workspace(workspace_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tags->createTagForWorkspace($workspace_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tags.create_tag_for_workspace(workspace_gid: 'workspace_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 6, "x-moar-complexity-skipped": false } }, "/task_templates": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get multiple task templates", "description": "Required scope: task_templates:read\n\nReturns the compact task template records for some filtered set of task templates. You must specify a `project`", "tags": [ "Task templates" ], "operationId": "getTaskTemplates", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "project", "in": "query", "description": "The project to filter task templates on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "project" }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "created_at", "created_by", "name", "project", "template" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "created_by", "name", "project", "template" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved requested task templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *task template* is an object that allows new tasks to be created with a predefined setup.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task_template", "x-insert-after": "gid" }, "name": { "description": "Name of the task template.", "type": "string", "example": "Packing list" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "task_templates:read" ] } ], "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet taskTemplatesApiInstance = new Asana.TaskTemplatesApi();\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'project': \"321654\", \n 'opt_fields': \"created_at,created_by,name,project,template\"\n};\ntaskTemplatesApiInstance.getTaskTemplates(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasktemplates.getTaskTemplates({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntask_templates_api_instance = asana.TaskTemplatesApi(api_client)\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'project': \"321654\", # str | The project to filter task templates on.\n 'opt_fields': \"created_at,created_by,name,project,template\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple task templates\n api_response = task_templates_api_instance.get_task_templates(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TaskTemplatesApi->get_task_templates: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.task_templates.get_task_templates({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/task_templates/{task_template_gid}": { "parameters": [ { "name": "task_template_gid", "in": "path", "description": "Globally unique identifier for the task template.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "task_template" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a task template", "description": "Required scope: task_templates:read\n\nReturns the complete task template record for a single task template.", "tags": [ "Task templates" ], "operationId": "getTaskTemplate", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "created_at", "created_by", "name", "project", "template" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "created_by", "name", "project", "template" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved requested task template", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *task template* is an object that allows new tasks to be created with a predefined setup.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task_template", "x-insert-after": "gid" }, "name": { "description": "Name of the task template.", "type": "string", "example": "Packing list" } } } ] }, { "type": "object", "properties": { "name": { "description": "Name of the task template.", "type": "string", "example": "Bug Report Template" }, "project": { "description": "The project that this task template belongs to.", "nullable": true, "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } ] }, "template": { "description": "The configuration for the task that will be created from this template.", "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "description": "Name of the task that will be created from this template.", "type": "string", "example": "Bug Report" }, "task_resource_subtype": { "type": "string", "description": "The subtype of the task that will be created from this template.", "enum": [ "default_task", "milestone_task", "approval_task" ], "example": "default_task" } } }, { "type": "object", "properties": { "description": { "description": "Description of the task that will be created from this template.", "type": "string", "example": "Please describe the bug you found and how to reproduce it." }, "html_description": { "description": "HTML description of the task that will be created from this template.", "type": "string", "example": "Please describe the bug you found and how to reproduce it." }, "memberships": { "description": "Array of projects that the task created from this template will be added to", "type": "array", "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "relative_start_on": { "nullable": true, "description": "The number of days after the task has been instantiated on which that the task will start", "type": "integer", "example": 1 }, "relative_due_on": { "nullable": true, "description": "The number of days after the task has been instantiated on which that the task will be due", "type": "integer", "example": 2 }, "due_time": { "nullable": true, "description": "The time of day that the task will be due", "type": "string", "example": "13:15:00.000Z" }, "dependencies": { "description": "Array of task templates that the task created from this template will depend on", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Name of the task that will be created from this template.", "type": "string", "example": "Bug Report" }, "task_resource_subtype": { "type": "string", "description": "The subtype of the task that will be created from this template.", "enum": [ "default_task", "milestone_task", "approval_task" ], "example": "default_task" } } } }, "dependents": { "description": "Array of task templates that will depend on the task created from this template", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Name of the task that will be created from this template.", "type": "string", "example": "Bug Report" }, "task_resource_subtype": { "type": "string", "description": "The subtype of the task that will be created from this template.", "enum": [ "default_task", "milestone_task", "approval_task" ], "example": "default_task" } } } }, "followers": { "description": "Array of users that will be added as followers to the task created from this template", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "attachments": { "description": "Array of attachments that will be added to the task created from this template", "type": "array", "items": { "description": "An *attachment* object represents any file attached to a task in Asana, whether it's an uploaded file or one associated via a third-party service such as Dropbox or Google Drive.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "attachment", "x-insert-after": "gid" }, "name": { "description": "The name of the file.", "type": "string", "readOnly": true, "example": "Screenshot.png" }, "resource_subtype": { "description": "The service hosting the attachment. Valid values are `asana`, `dropbox`, `gdrive`, `onedrive`, `box`, `vimeo`, and `external`.", "type": "string", "example": "dropbox" } } } }, "subtasks": { "description": "Array of subtasks that will be added to the task created from this template", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Name of the task that will be created from this template.", "type": "string", "example": "Bug Report" }, "task_resource_subtype": { "type": "string", "description": "The subtype of the task that will be created from this template.", "enum": [ "default_task", "milestone_task", "approval_task" ], "example": "default_task" } } } }, "custom_fields": { "description": "Array of custom fields that will be added to the task created from this template", "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } } } } ] } ] }, "created_by": { "description": "The user who created this task template.", "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } ] }, "created_at": { "description": "The time at which this task template was created.", "type": "string", "format": "date-time", "example": "2019-01-01T00:00:00.000Z" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "task_templates:read" ] } ], "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet taskTemplatesApiInstance = new Asana.TaskTemplatesApi();\nlet task_template_gid = \"1331\"; // String | Globally unique identifier for the task template.\nlet opts = { \n 'opt_fields': \"created_at,created_by,name,project,template\"\n};\ntaskTemplatesApiInstance.getTaskTemplate(task_template_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasktemplates.getTaskTemplate(taskTemplateGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntask_templates_api_instance = asana.TaskTemplatesApi(api_client)\ntask_template_gid = \"1331\" # str | Globally unique identifier for the task template.\nopts = {\n 'opt_fields': \"created_at,created_by,name,project,template\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a task template\n api_response = task_templates_api_instance.get_task_template(task_template_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TaskTemplatesApi->get_task_template: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.task_templates.get_task_template(task_template_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a task template", "description": "A specific, existing task template can be deleted by making a DELETE request on the URL for that task template. Returns an empty data record.", "tags": [ "Task templates" ], "operationId": "deleteTaskTemplate", "responses": { "200": { "description": "Successfully deleted the specified task template.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet taskTemplatesApiInstance = new Asana.TaskTemplatesApi();\nlet task_template_gid = \"1331\"; // String | Globally unique identifier for the task template.\n\ntaskTemplatesApiInstance.deleteTaskTemplate(task_template_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasktemplates.deleteTaskTemplate(taskTemplateGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntask_templates_api_instance = asana.TaskTemplatesApi(api_client)\ntask_template_gid = \"1331\" # str | Globally unique identifier for the task template.\n\n\ntry:\n # Delete a task template\n api_response = task_templates_api_instance.delete_task_template(task_template_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TaskTemplatesApi->delete_task_template: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.task_templates.delete_task_template(task_template_gid, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/task_templates/{task_template_gid}/instantiateTask": { "parameters": [ { "name": "task_template_gid", "in": "path", "description": "Globally unique identifier for the task template.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "task_template" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Instantiate a task from a task template", "description": "Creates and returns a job that will asynchronously handle the task instantiation.", "tags": [ "Task templates" ], "operationId": "instantiateTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "new_graph_export", "new_graph_export.completed_at", "new_graph_export.created_at", "new_graph_export.download_url", "new_project", "new_project.name", "new_project_template", "new_project_template.name", "new_resource_export", "new_resource_export.completed_at", "new_resource_export.created_at", "new_resource_export.download_url", "new_task", "new_task.created_by", "new_task.name", "new_task.resource_subtype", "new_task_template", "new_task_template.name", "resource_subtype", "status" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "new_graph_export", "new_graph_export.completed_at", "new_graph_export.created_at", "new_graph_export.download_url", "new_project", "new_project.name", "new_project_template", "new_project_template.name", "new_resource_export", "new_resource_export.completed_at", "new_resource_export.created_at", "new_resource_export.download_url", "new_task", "new_task.created_by", "new_task.name", "new_task.resource_subtype", "new_task_template", "new_task_template.name", "resource_subtype", "status" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Describes the inputs used for instantiating a task - the task's name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "description": "The name of the new task. If not provided, the name of the task template will be used.", "type": "string", "example": "New Task" } } } } } } } }, "responses": { "201": { "description": "Successfully created the job to handle task instantiation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A *job* is an object representing a process that handles asynchronous work.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "job", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "duplicate_task" }, "status": { "description": "The current status of this job.", "type": "string", "enum": [ "not_started", "in_progress", "succeeded", "failed" ], "readOnly": true, "example": "in_progress" }, "new_project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "new_task": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "nullable": true } ] }, "new_project_template": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, "new_graph_export": { "description": "A *graph_export* object represents a request to export the data starting from a parent object", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "graph_export", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin JSON format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or\nfailed. If present, this URL may only be valid for 1 hour from\nthe time of retrieval. You should avoid persisting this URL\nsomewhere and rather refresh on demand to ensure you do not keep\nstale URLs.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/domain_export/7588024658887731/download/ domain_export_2563645399633793_7588024658887731_2023018-201726.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Content-Sha256=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host&x-id=GetObject#_=_" }, "completed_at": { "description": "The time at which this resource was completed.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } }, "new_resource_export": { "description": "A *resource_export* object represents a request to bulk export objects for one or more resources.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "export_request", "x-insert-after": "gid" }, "created_at": { "description": "The time at which the resource export object was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin [JSON Lines](https://jsonlines.org/) format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or failed.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/object_export/7588024658887731/download/ object_export_2563645399633793_7588024658887731_2023018-201726.jsonl.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Credential=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host" }, "completed_at": { "description": "The time at which this resource was completed. This will be null if the export is still in progress.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet taskTemplatesApiInstance = new Asana.TaskTemplatesApi();\nlet task_template_gid = \"1331\"; // String | Globally unique identifier for the task template.\nlet opts = { \n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, \n 'opt_fields': \"new_graph_export,new_graph_export.completed_at,new_graph_export.created_at,new_graph_export.download_url,new_project,new_project.name,new_project_template,new_project_template.name,new_resource_export,new_resource_export.completed_at,new_resource_export.created_at,new_resource_export.download_url,new_task,new_task.created_by,new_task.name,new_task.resource_subtype,resource_subtype,status\"\n};\ntaskTemplatesApiInstance.instantiateTask(task_template_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasktemplates.instantiateTask(taskTemplateGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntask_templates_api_instance = asana.TaskTemplatesApi(api_client)\ntask_template_gid = \"1331\" # str | Globally unique identifier for the task template.\nopts = {\n 'body': {\"data\": {\"\": \"\", \"\": \"\",}}, # dict | Describes the inputs used for instantiating a task - the task's name.\n 'opt_fields': \"new_graph_export,new_graph_export.completed_at,new_graph_export.created_at,new_graph_export.download_url,new_project,new_project.name,new_project_template,new_project_template.name,new_resource_export,new_resource_export.completed_at,new_resource_export.created_at,new_resource_export.download_url,new_task,new_task.created_by,new_task.name,new_task.resource_subtype,resource_subtype,status\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Instantiate a task from a task template\n api_response = task_templates_api_instance.instantiate_task(task_template_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TaskTemplatesApi->instantiate_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.task_templates.instantiate_task(task_template_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/tasks": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get multiple tasks", "description": "Required scope: tasks:read\n\nReturns the compact task records for some filtered set of tasks. Use one or more of the parameters provided to filter the tasks returned. You must specify a `project` or `tag` if you do not specify `assignee` and `workspace`.\n\nFor more complex task retrieval, use [workspaces/{workspace_gid}/tasks/search](/reference/searchtasksforworkspace).", "tags": [ "Tasks" ], "operationId": "getTasks", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "assignee", "in": "query", "description": "The assignee to filter tasks on. If searching for unassigned tasks, assignee.any = null can be specified.\n*Note: If you specify `assignee`, you must also specify the `workspace` to filter on.*", "schema": { "type": "string" }, "x-env-variable": "assignee", "example": "14641" }, { "name": "project", "in": "query", "description": "The project to filter tasks on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "project" }, { "name": "section", "in": "query", "description": "The section to filter tasks on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "section" }, { "name": "workspace", "in": "query", "description": "The workspace to filter tasks on.\n*Note: If you specify `workspace`, you must also specify the `assignee` to filter on.*", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "workspace" }, { "name": "completed_since", "in": "query", "description": "Only return tasks that are either incomplete or that have been completed since this time.", "schema": { "type": "string", "format": "date-time", "example": "2012-02-22T02:06:58.158Z" } }, { "name": "modified_since", "in": "query", "description": "Only return tasks that have been modified since the given time.\n\n*Note: A task is considered \u201cmodified\u201d if any of its properties\nchange, or associations between it and other objects are modified\n(e.g. a task being added to a project). A task is not considered\nmodified just because another object it is associated with (e.g. a\nsubtask) is modified. Actions that count as modifying the task\ninclude assigning, renaming, completing, and adding stories.*", "schema": { "type": "string", "format": "date-time" }, "example": "2012-02-22T02:06:58.158Z" }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved requested tasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.tasks.getTasks(modifiedSince, completedSince, workspace, section, project, assignee)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'assignee': \"14641\", \n 'project': \"321654\", \n 'section': \"321654\", \n 'workspace': \"321654\", \n 'completed_since': \"2012-02-22T02:06:58.158Z\", \n 'modified_since': \"2012-02-22T02:06:58.158Z\", \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\"\n};\ntasksApiInstance.getTasks(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.getTasks({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'assignee': \"14641\", # str | The assignee to filter tasks on. If searching for unassigned tasks, assignee.any = null can be specified. *Note: If you specify `assignee`, you must also specify the `workspace` to filter on.*\n 'project': \"321654\", # str | The project to filter tasks on.\n 'section': \"321654\", # str | The section to filter tasks on.\n 'workspace': \"321654\", # str | The workspace to filter tasks on. *Note: If you specify `workspace`, you must also specify the `assignee` to filter on.*\n 'completed_since': '2012-02-22T02:06:58.158Z', # datetime | Only return tasks that are either incomplete or that have been completed since this time.\n 'modified_since': '2012-02-22T02:06:58.158Z', # datetime | Only return tasks that have been modified since the given time. *Note: A task is considered \u201cmodified\u201d if any of its properties change, or associations between it and other objects are modified (e.g. a task being added to a project). A task is not considered modified just because another object it is associated with (e.g. a subtask) is modified. Actions that count as modifying the task include assigning, renaming, completing, and adding stories.*\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple tasks\n api_response = tasks_api_instance.get_tasks(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->get_tasks: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.get_tasks({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->getTasks(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.get_tasks(param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a task", "description": "Required scope: tasks:write\n\nCreating a new task is as easy as POSTing to the `/tasks` endpoint with a\ndata block containing the fields you\u2019d like to set on the task. Any\nunspecified fields will take on default values.\n\nEvery task is required to be created in a specific workspace, and this\nworkspace cannot be changed once set. The workspace need not be set\nexplicitly if you specify `projects` or a `parent` task instead.", "tags": [ "Tasks" ], "operationId": "createTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The task to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "properties": { "approval_status": { "type": "string", "description": "*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.", "enum": [ "pending", "approved", "rejected", "changes_requested" ], "example": "pending" }, "assignee_status": { "description": "*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to \"inbox\" or \"upcoming\" inserts it at the top of the section, while the other options will insert at the bottom.", "type": "string", "enum": [ "today", "upcoming", "later", "new", "inbox" ], "example": "upcoming" }, "completed": { "description": "True if the task is currently marked complete, false if not.", "type": "boolean", "example": false }, "completed_at": { "description": "The time at which this task was completed, or null if the task is incomplete.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "readOnly": true, "nullable": true } ] }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "dependencies": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "dependents": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.147Z", "nullable": true }, "due_on": { "description": "The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.", "type": "string", "format": "date", "example": "2019-09-15", "nullable": true }, "external": { "description": "*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).\nThe external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.", "type": "object", "properties": { "gid": { "type": "string", "example": "1234" }, "data": { "type": "string", "example": "A blob of information." } }, "example": { "gid": "my_gid", "data": "A blob of information" } }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "hearted": { "description": "*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "is_rendered_as_separator": { "description": "[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`. This parameter only applies to regular tasks with `resource_subtype` of `default_task`. Tasks with `resource_subtype` of `milestone`, `approval`, or custom task types will not have this property and cannot be rendered as separators.", "type": "boolean", "example": false, "readOnly": true }, "liked": { "description": "True if the task is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "memberships": { "description": "

Full object requires scope: projects:read, project_sections:read

\n\n*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.", "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } } } } }, "modified_at": { "description": "The time at which this task was last modified.\n\nThe following conditions will change `modified_at`:\n\n- story is created on a task\n- story is trashed on a task\n- attachment is trashed on a task\n- task is assigned or unassigned\n- custom field value is changed\n- the task itself is trashed\n- Or if any of the following fields are updated:\n - completed\n - name\n - due_date\n - description\n - attachments\n - items\n - schedule_status\n\nThe following conditions will _not_ change `modified_at`:\n\n- moving to a new container (project, portfolio, etc)\n- comments being added to the task (but the stories they generate\n _will_ affect `modified_at`)", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "name": { "description": "Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Buy catnip" }, "notes": { "description": "Free-form textual information associated with the task (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this task.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this task.", "type": "integer", "example": 5, "readOnly": true }, "num_subtasks": { "description": "[Opt In](/docs/inputoutput-options). The number of subtasks on this task.\n", "type": "integer", "example": 3, "readOnly": true }, "start_at": { "description": "Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.\n*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*", "type": "string", "nullable": true, "format": "date-time", "example": "2019-09-14T02:06:58.147Z" }, "start_on": { "description": "The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.\n*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "actual_time_minutes": { "description": "

Full object requires scope: time_tracking_entries:read

\n\nThis value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.", "type": "number", "example": 200, "readOnly": true, "nullable": true } } } ] }, { "type": "object", "properties": { "assignee": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "Gid of a user.", "example": "12345", "nullable": true }, "assignee_section": { "nullable": true, "type": "string", "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list.", "example": "12345" }, "custom_fields": { "description": "An object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, object, or array (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.", "type": "object", "additionalProperties": { "type": "string", "description": "\"{custom_field_gid}\" => Value (can be text, a number, etc.). For date, use format \"YYYY-MM-DD\" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z)." }, "example": { "5678904321": "On Hold", "4578152156": "Not Started" } }, "followers": { "type": "array", "description": "*Create-Only* An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user. In order to change followers on an existing task use `addFollowers` and `removeFollowers`.", "items": { "type": "string", "description": "Gid of a user." }, "example": [ "12345" ] }, "parent": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "Gid of a task.", "example": "12345", "nullable": true }, "projects": { "type": "array", "description": "*Create-Only* Array of project gids. In order to change projects on an existing task use `addProject` and `removeProject`.", "items": { "type": "string", "description": "Gid of a project." }, "example": [ "12345" ] }, "tags": { "type": "array", "description": "*Create-Only* Array of tag gids. In order to change tags on an existing task use `addTag` and `removeTag`.", "items": { "type": "string", "description": "Gid of a tag." }, "example": [ "12345" ] }, "workspace": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "Gid of a workspace.", "example": "12345" }, "custom_type": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "GID or globally-unique identifier of a custom_type.", "example": "12345", "nullable": true }, "custom_type_status_option": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "GID or globally-unique identifier of a custom_type_status_option", "example": "12345", "nullable": true } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created a new task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "properties": { "approval_status": { "type": "string", "description": "*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.", "enum": [ "pending", "approved", "rejected", "changes_requested" ], "example": "pending" }, "assignee_status": { "description": "*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to \"inbox\" or \"upcoming\" inserts it at the top of the section, while the other options will insert at the bottom.", "type": "string", "enum": [ "today", "upcoming", "later", "new", "inbox" ], "example": "upcoming" }, "completed": { "description": "True if the task is currently marked complete, false if not.", "type": "boolean", "example": false }, "completed_at": { "description": "The time at which this task was completed, or null if the task is incomplete.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "readOnly": true, "nullable": true } ] }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "dependencies": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "dependents": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.147Z", "nullable": true }, "due_on": { "description": "The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.", "type": "string", "format": "date", "example": "2019-09-15", "nullable": true }, "external": { "description": "*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).\nThe external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.", "type": "object", "properties": { "gid": { "type": "string", "example": "1234" }, "data": { "type": "string", "example": "A blob of information." } }, "example": { "gid": "my_gid", "data": "A blob of information" } }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "hearted": { "description": "*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "is_rendered_as_separator": { "description": "[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`. This parameter only applies to regular tasks with `resource_subtype` of `default_task`. Tasks with `resource_subtype` of `milestone`, `approval`, or custom task types will not have this property and cannot be rendered as separators.", "type": "boolean", "example": false, "readOnly": true }, "liked": { "description": "True if the task is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "memberships": { "description": "

Full object requires scope: projects:read, project_sections:read

\n\n*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.", "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } } } } }, "modified_at": { "description": "The time at which this task was last modified.\n\nThe following conditions will change `modified_at`:\n\n- story is created on a task\n- story is trashed on a task\n- attachment is trashed on a task\n- task is assigned or unassigned\n- custom field value is changed\n- the task itself is trashed\n- Or if any of the following fields are updated:\n - completed\n - name\n - due_date\n - description\n - attachments\n - items\n - schedule_status\n\nThe following conditions will _not_ change `modified_at`:\n\n- moving to a new container (project, portfolio, etc)\n- comments being added to the task (but the stories they generate\n _will_ affect `modified_at`)", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "name": { "description": "Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Buy catnip" }, "notes": { "description": "Free-form textual information associated with the task (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this task.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this task.", "type": "integer", "example": 5, "readOnly": true }, "num_subtasks": { "description": "[Opt In](/docs/inputoutput-options). The number of subtasks on this task.\n", "type": "integer", "example": 3, "readOnly": true }, "start_at": { "description": "Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.\n*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*", "type": "string", "nullable": true, "format": "date-time", "example": "2019-09-14T02:06:58.147Z" }, "start_on": { "description": "The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.\n*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "actual_time_minutes": { "description": "

Full object requires scope: time_tracking_entries:read

\n\nThis value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.", "type": "number", "example": 200, "readOnly": true, "nullable": true } } } ] }, { "type": "object", "properties": { "assignee": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "assignee_section": { "allOf": [ { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, { "type": "object", "nullable": true, "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list." } ] }, "custom_fields": { "description": "Array of custom field values applied to the task. These represent the custom field values recorded on this project for a particular custom field. For example, these custom field values will contain an `enum_value` property for custom fields of type `enum`, a `text_value` property for custom fields of type `text`, and so on. Please note that the `gid` returned on each custom field value *is identical* to the `gid` of the custom field, which allows referencing the custom field metadata through the `/custom_fields/custom_field_gid` endpoint.", "type": "array", "items": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, "readOnly": true }, "custom_type": { "allOf": [ { "description": "Custom Types extend the types of Asana Objects, currently only Custom Tasks are supported.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type.", "example": "Bug ticket" } } }, { "nullable": true } ] }, "custom_type_status_option": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type_status_option", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type status option.", "example": "Solution pending" } } }, { "nullable": true } ] }, "followers": { "description": "Array of users following this task.", "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "parent": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "readOnly": true, "description": "The parent of this task, or `null` if this is not a subtask. This property cannot be modified using a PUT request but you can change it with the `setParent` endpoint. You can create subtasks by using the subtasks endpoint.", "nullable": true } ] }, "projects": { "description": "*Create-only.* Array of projects this task is associated with. At task creation time, this array can be used to add the task to many projects at once. After task creation, these associations can be modified using the addProject and removeProject endpoints.", "type": "array", "readOnly": true, "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "tags": { "description": "Array of tags associated with this task. In order to change tags on an existing task use `addTag` and `removeTag`.", "type": "array", "readOnly": true, "items": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "example": [ { "gid": "59746", "name": "Grade A" } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace this task is associated with. Once created, task cannot be moved to a different workspace. This attribute can only be specified at creation time." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/task/123456789" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTask result = client.tasks.createTask()\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The task to create.\nlet opts = { \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\"\n};\ntasksApiInstance.createTask(body, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.createTask({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The task to create.\nopts = {\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a task\n api_response = tasks_api_instance.create_task(body, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->create_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.create_task({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->createTask(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.create_task(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 58, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a task", "description": "Required scope: tasks:read\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
FieldRequired Scope
membershipsprojects:read, project_sections:read
actual_time_minutestime_tracking_entries:read
\n\nReturns the complete task record for a single task.", "tags": [ "Tasks" ], "operationId": "getTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "properties": { "approval_status": { "type": "string", "description": "*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.", "enum": [ "pending", "approved", "rejected", "changes_requested" ], "example": "pending" }, "assignee_status": { "description": "*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to \"inbox\" or \"upcoming\" inserts it at the top of the section, while the other options will insert at the bottom.", "type": "string", "enum": [ "today", "upcoming", "later", "new", "inbox" ], "example": "upcoming" }, "completed": { "description": "True if the task is currently marked complete, false if not.", "type": "boolean", "example": false }, "completed_at": { "description": "The time at which this task was completed, or null if the task is incomplete.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "readOnly": true, "nullable": true } ] }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "dependencies": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "dependents": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.147Z", "nullable": true }, "due_on": { "description": "The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.", "type": "string", "format": "date", "example": "2019-09-15", "nullable": true }, "external": { "description": "*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).\nThe external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.", "type": "object", "properties": { "gid": { "type": "string", "example": "1234" }, "data": { "type": "string", "example": "A blob of information." } }, "example": { "gid": "my_gid", "data": "A blob of information" } }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "hearted": { "description": "*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "is_rendered_as_separator": { "description": "[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`. This parameter only applies to regular tasks with `resource_subtype` of `default_task`. Tasks with `resource_subtype` of `milestone`, `approval`, or custom task types will not have this property and cannot be rendered as separators.", "type": "boolean", "example": false, "readOnly": true }, "liked": { "description": "True if the task is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "memberships": { "description": "

Full object requires scope: projects:read, project_sections:read

\n\n*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.", "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } } } } }, "modified_at": { "description": "The time at which this task was last modified.\n\nThe following conditions will change `modified_at`:\n\n- story is created on a task\n- story is trashed on a task\n- attachment is trashed on a task\n- task is assigned or unassigned\n- custom field value is changed\n- the task itself is trashed\n- Or if any of the following fields are updated:\n - completed\n - name\n - due_date\n - description\n - attachments\n - items\n - schedule_status\n\nThe following conditions will _not_ change `modified_at`:\n\n- moving to a new container (project, portfolio, etc)\n- comments being added to the task (but the stories they generate\n _will_ affect `modified_at`)", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "name": { "description": "Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Buy catnip" }, "notes": { "description": "Free-form textual information associated with the task (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this task.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this task.", "type": "integer", "example": 5, "readOnly": true }, "num_subtasks": { "description": "[Opt In](/docs/inputoutput-options). The number of subtasks on this task.\n", "type": "integer", "example": 3, "readOnly": true }, "start_at": { "description": "Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.\n*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*", "type": "string", "nullable": true, "format": "date-time", "example": "2019-09-14T02:06:58.147Z" }, "start_on": { "description": "The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.\n*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "actual_time_minutes": { "description": "

Full object requires scope: time_tracking_entries:read

\n\nThis value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.", "type": "number", "example": 200, "readOnly": true, "nullable": true } } } ] }, { "type": "object", "properties": { "assignee": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "assignee_section": { "allOf": [ { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, { "type": "object", "nullable": true, "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list." } ] }, "custom_fields": { "description": "Array of custom field values applied to the task. These represent the custom field values recorded on this project for a particular custom field. For example, these custom field values will contain an `enum_value` property for custom fields of type `enum`, a `text_value` property for custom fields of type `text`, and so on. Please note that the `gid` returned on each custom field value *is identical* to the `gid` of the custom field, which allows referencing the custom field metadata through the `/custom_fields/custom_field_gid` endpoint.", "type": "array", "items": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, "readOnly": true }, "custom_type": { "allOf": [ { "description": "Custom Types extend the types of Asana Objects, currently only Custom Tasks are supported.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type.", "example": "Bug ticket" } } }, { "nullable": true } ] }, "custom_type_status_option": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type_status_option", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type status option.", "example": "Solution pending" } } }, { "nullable": true } ] }, "followers": { "description": "Array of users following this task.", "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "parent": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "readOnly": true, "description": "The parent of this task, or `null` if this is not a subtask. This property cannot be modified using a PUT request but you can change it with the `setParent` endpoint. You can create subtasks by using the subtasks endpoint.", "nullable": true } ] }, "projects": { "description": "*Create-only.* Array of projects this task is associated with. At task creation time, this array can be used to add the task to many projects at once. After task creation, these associations can be modified using the addProject and removeProject endpoints.", "type": "array", "readOnly": true, "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "tags": { "description": "Array of tags associated with this task. In order to change tags on an existing task use `addTag` and `removeTag`.", "type": "array", "readOnly": true, "items": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "example": [ { "gid": "59746", "name": "Grade A" } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace this task is associated with. Once created, task cannot be moved to a different workspace. This attribute can only be specified at creation time." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/task/123456789" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTask result = client.tasks.getTask(taskGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\"\n};\ntasksApiInstance.getTask(task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.getTask(taskGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a task\n api_response = tasks_api_instance.get_task(task_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->get_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.get_task(task_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->getTask($task_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.get_task(task_gid: 'task_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a task", "description": "Required scope: tasks:write\n\nA specific, existing task can be updated by making a PUT request on the\nURL for that task. Only the fields provided in the `data` block will be\nupdated; any unspecified fields will remain unchanged.\n\nWhen using this method, it is best to specify only those fields you wish\nto change, or else you may overwrite changes made by another user since\nyou last retrieved the task.\n\nReturns the complete updated task record.", "tags": [ "Tasks" ], "operationId": "updateTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The task to update.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "properties": { "approval_status": { "type": "string", "description": "*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.", "enum": [ "pending", "approved", "rejected", "changes_requested" ], "example": "pending" }, "assignee_status": { "description": "*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to \"inbox\" or \"upcoming\" inserts it at the top of the section, while the other options will insert at the bottom.", "type": "string", "enum": [ "today", "upcoming", "later", "new", "inbox" ], "example": "upcoming" }, "completed": { "description": "True if the task is currently marked complete, false if not.", "type": "boolean", "example": false }, "completed_at": { "description": "The time at which this task was completed, or null if the task is incomplete.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "readOnly": true, "nullable": true } ] }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "dependencies": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "dependents": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.147Z", "nullable": true }, "due_on": { "description": "The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.", "type": "string", "format": "date", "example": "2019-09-15", "nullable": true }, "external": { "description": "*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).\nThe external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.", "type": "object", "properties": { "gid": { "type": "string", "example": "1234" }, "data": { "type": "string", "example": "A blob of information." } }, "example": { "gid": "my_gid", "data": "A blob of information" } }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "hearted": { "description": "*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "is_rendered_as_separator": { "description": "[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`. This parameter only applies to regular tasks with `resource_subtype` of `default_task`. Tasks with `resource_subtype` of `milestone`, `approval`, or custom task types will not have this property and cannot be rendered as separators.", "type": "boolean", "example": false, "readOnly": true }, "liked": { "description": "True if the task is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "memberships": { "description": "

Full object requires scope: projects:read, project_sections:read

\n\n*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.", "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } } } } }, "modified_at": { "description": "The time at which this task was last modified.\n\nThe following conditions will change `modified_at`:\n\n- story is created on a task\n- story is trashed on a task\n- attachment is trashed on a task\n- task is assigned or unassigned\n- custom field value is changed\n- the task itself is trashed\n- Or if any of the following fields are updated:\n - completed\n - name\n - due_date\n - description\n - attachments\n - items\n - schedule_status\n\nThe following conditions will _not_ change `modified_at`:\n\n- moving to a new container (project, portfolio, etc)\n- comments being added to the task (but the stories they generate\n _will_ affect `modified_at`)", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "name": { "description": "Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Buy catnip" }, "notes": { "description": "Free-form textual information associated with the task (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this task.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this task.", "type": "integer", "example": 5, "readOnly": true }, "num_subtasks": { "description": "[Opt In](/docs/inputoutput-options). The number of subtasks on this task.\n", "type": "integer", "example": 3, "readOnly": true }, "start_at": { "description": "Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.\n*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*", "type": "string", "nullable": true, "format": "date-time", "example": "2019-09-14T02:06:58.147Z" }, "start_on": { "description": "The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.\n*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "actual_time_minutes": { "description": "

Full object requires scope: time_tracking_entries:read

\n\nThis value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.", "type": "number", "example": 200, "readOnly": true, "nullable": true } } } ] }, { "type": "object", "properties": { "assignee": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "Gid of a user.", "example": "12345", "nullable": true }, "assignee_section": { "nullable": true, "type": "string", "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list.", "example": "12345" }, "custom_fields": { "description": "An object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, object, or array (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.", "type": "object", "additionalProperties": { "type": "string", "description": "\"{custom_field_gid}\" => Value (can be text, a number, etc.). For date, use format \"YYYY-MM-DD\" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z)." }, "example": { "5678904321": "On Hold", "4578152156": "Not Started" } }, "followers": { "type": "array", "description": "*Create-Only* An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user. In order to change followers on an existing task use `addFollowers` and `removeFollowers`.", "items": { "type": "string", "description": "Gid of a user." }, "example": [ "12345" ] }, "parent": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "Gid of a task.", "example": "12345", "nullable": true }, "projects": { "type": "array", "description": "*Create-Only* Array of project gids. In order to change projects on an existing task use `addProject` and `removeProject`.", "items": { "type": "string", "description": "Gid of a project." }, "example": [ "12345" ] }, "tags": { "type": "array", "description": "*Create-Only* Array of tag gids. In order to change tags on an existing task use `addTag` and `removeTag`.", "items": { "type": "string", "description": "Gid of a tag." }, "example": [ "12345" ] }, "workspace": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "Gid of a workspace.", "example": "12345" }, "custom_type": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "GID or globally-unique identifier of a custom_type.", "example": "12345", "nullable": true }, "custom_type_status_option": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "GID or globally-unique identifier of a custom_type_status_option", "example": "12345", "nullable": true } } } ] } } } } } }, "responses": { "200": { "description": "Successfully updated the specified task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "properties": { "approval_status": { "type": "string", "description": "*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.", "enum": [ "pending", "approved", "rejected", "changes_requested" ], "example": "pending" }, "assignee_status": { "description": "*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to \"inbox\" or \"upcoming\" inserts it at the top of the section, while the other options will insert at the bottom.", "type": "string", "enum": [ "today", "upcoming", "later", "new", "inbox" ], "example": "upcoming" }, "completed": { "description": "True if the task is currently marked complete, false if not.", "type": "boolean", "example": false }, "completed_at": { "description": "The time at which this task was completed, or null if the task is incomplete.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "readOnly": true, "nullable": true } ] }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "dependencies": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "dependents": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.147Z", "nullable": true }, "due_on": { "description": "The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.", "type": "string", "format": "date", "example": "2019-09-15", "nullable": true }, "external": { "description": "*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).\nThe external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.", "type": "object", "properties": { "gid": { "type": "string", "example": "1234" }, "data": { "type": "string", "example": "A blob of information." } }, "example": { "gid": "my_gid", "data": "A blob of information" } }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "hearted": { "description": "*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "is_rendered_as_separator": { "description": "[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`. This parameter only applies to regular tasks with `resource_subtype` of `default_task`. Tasks with `resource_subtype` of `milestone`, `approval`, or custom task types will not have this property and cannot be rendered as separators.", "type": "boolean", "example": false, "readOnly": true }, "liked": { "description": "True if the task is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "memberships": { "description": "

Full object requires scope: projects:read, project_sections:read

\n\n*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.", "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } } } } }, "modified_at": { "description": "The time at which this task was last modified.\n\nThe following conditions will change `modified_at`:\n\n- story is created on a task\n- story is trashed on a task\n- attachment is trashed on a task\n- task is assigned or unassigned\n- custom field value is changed\n- the task itself is trashed\n- Or if any of the following fields are updated:\n - completed\n - name\n - due_date\n - description\n - attachments\n - items\n - schedule_status\n\nThe following conditions will _not_ change `modified_at`:\n\n- moving to a new container (project, portfolio, etc)\n- comments being added to the task (but the stories they generate\n _will_ affect `modified_at`)", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "name": { "description": "Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Buy catnip" }, "notes": { "description": "Free-form textual information associated with the task (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this task.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this task.", "type": "integer", "example": 5, "readOnly": true }, "num_subtasks": { "description": "[Opt In](/docs/inputoutput-options). The number of subtasks on this task.\n", "type": "integer", "example": 3, "readOnly": true }, "start_at": { "description": "Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.\n*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*", "type": "string", "nullable": true, "format": "date-time", "example": "2019-09-14T02:06:58.147Z" }, "start_on": { "description": "The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.\n*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "actual_time_minutes": { "description": "

Full object requires scope: time_tracking_entries:read

\n\nThis value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.", "type": "number", "example": 200, "readOnly": true, "nullable": true } } } ] }, { "type": "object", "properties": { "assignee": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "assignee_section": { "allOf": [ { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, { "type": "object", "nullable": true, "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list." } ] }, "custom_fields": { "description": "Array of custom field values applied to the task. These represent the custom field values recorded on this project for a particular custom field. For example, these custom field values will contain an `enum_value` property for custom fields of type `enum`, a `text_value` property for custom fields of type `text`, and so on. Please note that the `gid` returned on each custom field value *is identical* to the `gid` of the custom field, which allows referencing the custom field metadata through the `/custom_fields/custom_field_gid` endpoint.", "type": "array", "items": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, "readOnly": true }, "custom_type": { "allOf": [ { "description": "Custom Types extend the types of Asana Objects, currently only Custom Tasks are supported.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type.", "example": "Bug ticket" } } }, { "nullable": true } ] }, "custom_type_status_option": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type_status_option", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type status option.", "example": "Solution pending" } } }, { "nullable": true } ] }, "followers": { "description": "Array of users following this task.", "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "parent": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "readOnly": true, "description": "The parent of this task, or `null` if this is not a subtask. This property cannot be modified using a PUT request but you can change it with the `setParent` endpoint. You can create subtasks by using the subtasks endpoint.", "nullable": true } ] }, "projects": { "description": "*Create-only.* Array of projects this task is associated with. At task creation time, this array can be used to add the task to many projects at once. After task creation, these associations can be modified using the addProject and removeProject endpoints.", "type": "array", "readOnly": true, "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "tags": { "description": "Array of tags associated with this task. In order to change tags on an existing task use `addTag` and `removeTag`.", "type": "array", "readOnly": true, "items": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "example": [ { "gid": "59746", "name": "Grade A" } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace this task is associated with. Once created, task cannot be moved to a different workspace. This attribute can only be specified at creation time." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/task/123456789" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTask result = client.tasks.updateTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The task to update.\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\"\n};\ntasksApiInstance.updateTask(body, task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.updateTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The task to update.\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a task\n api_response = tasks_api_instance.update_task(body, task_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->update_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.update_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->updateTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.update_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 58, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a task", "description": "Required scope: tasks:delete\n\nA specific, existing task can be deleted by making a DELETE request on\nthe URL for that task. Deleted tasks go into the \u201ctrash\u201d of the user\nmaking the delete request. Tasks can be recovered from the trash within a\nperiod of 30 days; afterward they are completely removed from the system.\n\nReturns an empty data record.", "tags": [ "Tasks" ], "operationId": "deleteTask", "responses": { "200": { "description": "Successfully deleted the specified task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:delete" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.tasks.deleteTask(taskGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet task_gid = \"321654\"; // String | The task to operate on.\n\ntasksApiInstance.deleteTask(task_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.deleteTask(taskGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\ntask_gid = \"321654\" # str | The task to operate on.\n\n\ntry:\n # Delete a task\n api_response = tasks_api_instance.delete_task(task_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->delete_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.delete_task(task_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->deleteTask($task_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.delete_task(task_gid: 'task_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/duplicate": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Duplicate a task", "description": "Required scope: tasks:write\n\nCreates and returns a job that will asynchronously handle the duplication.", "tags": [ "Tasks" ], "operationId": "duplicateTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "new_graph_export", "new_graph_export.completed_at", "new_graph_export.created_at", "new_graph_export.download_url", "new_project", "new_project.name", "new_project_template", "new_project_template.name", "new_resource_export", "new_resource_export.completed_at", "new_resource_export.created_at", "new_resource_export.download_url", "new_task", "new_task.created_by", "new_task.name", "new_task.resource_subtype", "new_task_template", "new_task_template.name", "resource_subtype", "status" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "new_graph_export", "new_graph_export.completed_at", "new_graph_export.created_at", "new_graph_export.download_url", "new_project", "new_project.name", "new_project_template", "new_project_template.name", "new_resource_export", "new_resource_export.completed_at", "new_resource_export.created_at", "new_resource_export.download_url", "new_task", "new_task.created_by", "new_task.name", "new_task.resource_subtype", "new_task_template", "new_task_template.name", "resource_subtype", "status" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Describes the duplicate's name and the fields that will be duplicated.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "description": "The name of the new task.", "type": "string", "example": "New Task Name" }, "include": { "description": "A comma-separated list of fields that will be duplicated to the new task.\n##### Fields\n- assignee\n- attachments\n- dates\n- dependencies\n- followers\n- notes\n- parent\n- projects\n- subtasks\n- tags", "type": "string", "pattern": "([notes|assignee|subtasks|attachments|tags|followers|projects|dates|dependencies|parent])(,\\1)*", "example": [ "notes,assignee,subtasks,attachments,tags,followers,projects,dates,dependencies,parent" ] } } } } } } } }, "responses": { "201": { "description": "Successfully created the job to handle duplication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A *job* is an object representing a process that handles asynchronous work.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "job", "x-insert-after": "gid" }, "resource_subtype": { "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.", "type": "string", "readOnly": true, "example": "duplicate_task" }, "status": { "description": "The current status of this job.", "type": "string", "enum": [ "not_started", "in_progress", "succeeded", "failed" ], "readOnly": true, "example": "in_progress" }, "new_project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "new_task": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "nullable": true } ] }, "new_project_template": { "description": "A *project template* is an object that allows new projects to be created with a predefined setup, which may include tasks, sections, Rules, etc. It simplifies the process of running a workflow that involves a similar set of work every time.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project_template", "x-insert-after": "gid" }, "name": { "description": "Name of the project template.", "type": "string", "example": "Packing list" } } }, "new_graph_export": { "description": "A *graph_export* object represents a request to export the data starting from a parent object", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "graph_export", "x-insert-after": "gid" }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin JSON format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or\nfailed. If present, this URL may only be valid for 1 hour from\nthe time of retrieval. You should avoid persisting this URL\nsomewhere and rather refresh on demand to ensure you do not keep\nstale URLs.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/domain_export/7588024658887731/download/ domain_export_2563645399633793_7588024658887731_2023018-201726.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Content-Sha256=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host&x-id=GetObject#_=_" }, "completed_at": { "description": "The time at which this resource was completed.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } }, "new_resource_export": { "description": "A *resource_export* object represents a request to bulk export objects for one or more resources.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "export_request", "x-insert-after": "gid" }, "created_at": { "description": "The time at which the resource export object was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "download_url": { "description": "Download this URL to retrieve the full export\nin [JSON Lines](https://jsonlines.org/) format. It will be compressed in a gzip (.gz) container.\n\n*Note: May be null if the export is still in progress or failed.*", "type": "string", "format": "uri", "readOnly": true, "nullable": true, "example": "https://asana-export-us-east-1.s3.us-east-1.amazonaws.com/2563645399633793/object_export/7588024658887731/download/ object_export_2563645399633793_7588024658887731_2023018-201726.jsonl.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Credential=xxxxxxxx&X-Amz-Date=xxxxxxxx&X-Amz-Expires=300&X-Amz-Security-Token=xxxxxxxx& X-Amz-Signature=xxxxxxxx&X-Amz-SignedHeaders=host" }, "completed_at": { "description": "The time at which this resource was completed. This will be null if the export is still in progress.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T03:06:58.147Z" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJob result = client.tasks.duplicateTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Describes the duplicate's name and the fields that will be duplicated.\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'opt_fields': \"new_graph_export,new_graph_export.completed_at,new_graph_export.created_at,new_graph_export.download_url,new_project,new_project.name,new_project_template,new_project_template.name,new_resource_export,new_resource_export.completed_at,new_resource_export.created_at,new_resource_export.download_url,new_task,new_task.created_by,new_task.name,new_task.resource_subtype,resource_subtype,status\"\n};\ntasksApiInstance.duplicateTask(body, task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.duplicateTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Describes the duplicate's name and the fields that will be duplicated.\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'opt_fields': \"new_graph_export,new_graph_export.completed_at,new_graph_export.created_at,new_graph_export.download_url,new_project,new_project.name,new_project_template,new_project_template.name,new_resource_export,new_resource_export.completed_at,new_resource_export.created_at,new_resource_export.download_url,new_task,new_task.created_by,new_task.name,new_task.resource_subtype,resource_subtype,status\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Duplicate a task\n api_response = tasks_api_instance.duplicate_task(body, task_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->duplicate_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.duplicate_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->duplicateTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.duplicate_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 2, "x-moar-complexity-skipped": false } }, "/projects/{project_gid}/tasks": { "parameters": [ { "name": "completed_since", "in": "query", "required": false, "description": "Only return tasks that are either incomplete or that have been completed since this time. Accepts a date-time string or the keyword *now*.\n", "schema": { "type": "string" }, "example": "2012-02-22T02:06:58.158Z" }, { "name": "project_gid", "in": "path", "description": "Globally unique identifier for the project.", "required": true, "schema": { "type": "string" }, "example": "1331", "x-env-variable": "project" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get tasks from a project", "description": "Required scope: tasks:read\n\nReturns the compact task records for all tasks within the given project, ordered by their priority within the project. Tasks can exist in more than one project at a time.", "tags": [ "Tasks" ], "operationId": "getTasksForProject", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested project's tasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.tasks.getTasksForProject(projectGid, completedSince)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet project_gid = \"1331\"; // String | Globally unique identifier for the project.\nlet opts = { \n 'completed_since': \"2012-02-22T02:06:58.158Z\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\"\n};\ntasksApiInstance.getTasksForProject(project_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.getTasksForProject(projectGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nproject_gid = \"1331\" # str | Globally unique identifier for the project.\nopts = {\n 'completed_since': \"2012-02-22T02:06:58.158Z\", # str | Only return tasks that are either incomplete or that have been completed since this time. Accepts a date-time string or the keyword *now*. \n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get tasks from a project\n api_response = tasks_api_instance.get_tasks_for_project(project_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->get_tasks_for_project: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.get_tasks_for_project(project_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->getTasksForProject($project_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.get_tasks_for_project(project_gid: 'project_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/sections/{section_gid}/tasks": { "parameters": [ { "name": "section_gid", "in": "path", "required": true, "description": "The globally unique identifier for the section.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "section" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "completed_since", "in": "query", "required": false, "description": "Only return tasks that are either incomplete or that have been completed since this time. Accepts a date-time string or the keyword *now*.\n", "schema": { "type": "string" }, "example": "2012-02-22T02:06:58.158Z" } ], "get": { "summary": "Get tasks from a section", "description": "Required scope: tasks:read\n\n*Board view only*: Returns the compact section records for all tasks within the given section.", "tags": [ "Tasks" ], "operationId": "getTasksForSection", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the section's tasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.tasks.getTasksForSection(sectionGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet section_gid = \"321654\"; // String | The globally unique identifier for the section.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'completed_since': \"2012-02-22T02:06:58.158Z\", \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\"\n};\ntasksApiInstance.getTasksForSection(section_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.getTasksForSection(sectionGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nsection_gid = \"321654\" # str | The globally unique identifier for the section.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'completed_since': \"2012-02-22T02:06:58.158Z\", # str | Only return tasks that are either incomplete or that have been completed since this time. Accepts a date-time string or the keyword *now*. \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get tasks from a section\n api_response = tasks_api_instance.get_tasks_for_section(section_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->get_tasks_for_section: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.get_tasks_for_section(section_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->getTasksForSection($section_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.get_tasks_for_section(section_gid: 'section_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/tags/{tag_gid}/tasks": { "parameters": [ { "name": "tag_gid", "in": "path", "description": "Globally unique identifier for the tag.", "required": true, "schema": { "type": "string" }, "example": "11235", "x-env-variable": "tag" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get tasks from a tag", "description": "Required scope: tasks:read\n\nReturns the compact task records for all tasks with the given tag. Tasks can have more than one tag at a time.", "tags": [ "Tasks" ], "operationId": "getTasksForTag", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the tasks associated with the specified tag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.tasks.getTasksForTag(tagGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet tag_gid = \"11235\"; // String | Globally unique identifier for the tag.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\"\n};\ntasksApiInstance.getTasksForTag(tag_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.getTasksForTag(tagGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\ntag_gid = \"11235\" # str | Globally unique identifier for the tag.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get tasks from a tag\n api_response = tasks_api_instance.get_tasks_for_tag(tag_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->get_tasks_for_tag: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.get_tasks_for_tag(tag_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->getTasksForTag($tag_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.get_tasks_for_tag(tag_gid: 'tag_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/user_task_lists/{user_task_list_gid}/tasks": { "parameters": [ { "name": "completed_since", "in": "query", "required": false, "description": "Only return tasks that are either incomplete or that have been completed since this time. Accepts a date-time string or the keyword *now*.\n", "schema": { "type": "string" }, "example": "2012-02-22T02:06:58.158Z" }, { "name": "user_task_list_gid", "in": "path", "description": "Globally unique identifier for the user task list.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "user_task_list" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get tasks from a user task list", "description": "Required scope: tasks:read\n\nReturns the compact list of tasks in a user\u2019s My Tasks list.\n*Note: Access control is enforced for this endpoint as with all Asana API endpoints, meaning a user\u2019s private tasks will be filtered out if the API-authenticated user does not have access to them.*\n*Note: Both complete and incomplete tasks are returned by default unless they are filtered out (for example, setting `completed_since=now` will return only incomplete tasks, which is the default view for \u201cMy Tasks\u201d in Asana.)*", "tags": [ "Tasks" ], "operationId": "getTasksForUserTaskList", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the user task list's tasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.tasks.getTasksForUserTaskList(userTaskListGid, completedSince)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet user_task_list_gid = \"12345\"; // String | Globally unique identifier for the user task list.\nlet opts = { \n 'completed_since': \"2012-02-22T02:06:58.158Z\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\"\n};\ntasksApiInstance.getTasksForUserTaskList(user_task_list_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.getTasksForUserTaskList(userTaskListGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nuser_task_list_gid = \"12345\" # str | Globally unique identifier for the user task list.\nopts = {\n 'completed_since': \"2012-02-22T02:06:58.158Z\", # str | Only return tasks that are either incomplete or that have been completed since this time. Accepts a date-time string or the keyword *now*. \n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get tasks from a user task list\n api_response = tasks_api_instance.get_tasks_for_user_task_list(user_task_list_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->get_tasks_for_user_task_list: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.get_tasks_for_user_task_list(user_task_list_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->getTasksForUserTaskList($user_task_list_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.get_tasks_for_user_task_list(user_task_list_gid: 'user_task_list_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/subtasks": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get subtasks from a task", "description": "Required scope: tasks:read\n\nReturns a compact representation of all of the subtasks of a task.", "tags": [ "Tasks" ], "operationId": "getSubtasksForTask", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified task's subtasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.tasks.getSubtasksForTask(taskGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\"\n};\ntasksApiInstance.getSubtasksForTask(task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.getSubtasksForTask(taskGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get subtasks from a task\n api_response = tasks_api_instance.get_subtasks_for_task(task_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->get_subtasks_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.get_subtasks_for_task(task_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->getSubtasksForTask($task_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.get_subtasks_for_task(task_gid: 'task_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a subtask", "description": "Required scope: tasks:write\n\nCreates a new subtask and adds it to the parent task. Returns the full record for the newly created subtask.", "tags": [ "Tasks" ], "operationId": "createSubtaskForTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The new subtask to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "properties": { "approval_status": { "type": "string", "description": "*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.", "enum": [ "pending", "approved", "rejected", "changes_requested" ], "example": "pending" }, "assignee_status": { "description": "*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to \"inbox\" or \"upcoming\" inserts it at the top of the section, while the other options will insert at the bottom.", "type": "string", "enum": [ "today", "upcoming", "later", "new", "inbox" ], "example": "upcoming" }, "completed": { "description": "True if the task is currently marked complete, false if not.", "type": "boolean", "example": false }, "completed_at": { "description": "The time at which this task was completed, or null if the task is incomplete.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "readOnly": true, "nullable": true } ] }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "dependencies": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "dependents": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.147Z", "nullable": true }, "due_on": { "description": "The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.", "type": "string", "format": "date", "example": "2019-09-15", "nullable": true }, "external": { "description": "*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).\nThe external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.", "type": "object", "properties": { "gid": { "type": "string", "example": "1234" }, "data": { "type": "string", "example": "A blob of information." } }, "example": { "gid": "my_gid", "data": "A blob of information" } }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "hearted": { "description": "*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "is_rendered_as_separator": { "description": "[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`. This parameter only applies to regular tasks with `resource_subtype` of `default_task`. Tasks with `resource_subtype` of `milestone`, `approval`, or custom task types will not have this property and cannot be rendered as separators.", "type": "boolean", "example": false, "readOnly": true }, "liked": { "description": "True if the task is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "memberships": { "description": "

Full object requires scope: projects:read, project_sections:read

\n\n*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.", "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } } } } }, "modified_at": { "description": "The time at which this task was last modified.\n\nThe following conditions will change `modified_at`:\n\n- story is created on a task\n- story is trashed on a task\n- attachment is trashed on a task\n- task is assigned or unassigned\n- custom field value is changed\n- the task itself is trashed\n- Or if any of the following fields are updated:\n - completed\n - name\n - due_date\n - description\n - attachments\n - items\n - schedule_status\n\nThe following conditions will _not_ change `modified_at`:\n\n- moving to a new container (project, portfolio, etc)\n- comments being added to the task (but the stories they generate\n _will_ affect `modified_at`)", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "name": { "description": "Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Buy catnip" }, "notes": { "description": "Free-form textual information associated with the task (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this task.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this task.", "type": "integer", "example": 5, "readOnly": true }, "num_subtasks": { "description": "[Opt In](/docs/inputoutput-options). The number of subtasks on this task.\n", "type": "integer", "example": 3, "readOnly": true }, "start_at": { "description": "Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.\n*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*", "type": "string", "nullable": true, "format": "date-time", "example": "2019-09-14T02:06:58.147Z" }, "start_on": { "description": "The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.\n*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "actual_time_minutes": { "description": "

Full object requires scope: time_tracking_entries:read

\n\nThis value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.", "type": "number", "example": 200, "readOnly": true, "nullable": true } } } ] }, { "type": "object", "properties": { "assignee": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "Gid of a user.", "example": "12345", "nullable": true }, "assignee_section": { "nullable": true, "type": "string", "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list.", "example": "12345" }, "custom_fields": { "description": "An object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, object, or array (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.", "type": "object", "additionalProperties": { "type": "string", "description": "\"{custom_field_gid}\" => Value (can be text, a number, etc.). For date, use format \"YYYY-MM-DD\" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z)." }, "example": { "5678904321": "On Hold", "4578152156": "Not Started" } }, "followers": { "type": "array", "description": "*Create-Only* An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user. In order to change followers on an existing task use `addFollowers` and `removeFollowers`.", "items": { "type": "string", "description": "Gid of a user." }, "example": [ "12345" ] }, "parent": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "Gid of a task.", "example": "12345", "nullable": true }, "projects": { "type": "array", "description": "*Create-Only* Array of project gids. In order to change projects on an existing task use `addProject` and `removeProject`.", "items": { "type": "string", "description": "Gid of a project." }, "example": [ "12345" ] }, "tags": { "type": "array", "description": "*Create-Only* Array of tag gids. In order to change tags on an existing task use `addTag` and `removeTag`.", "items": { "type": "string", "description": "Gid of a tag." }, "example": [ "12345" ] }, "workspace": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "Gid of a workspace.", "example": "12345" }, "custom_type": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "GID or globally-unique identifier of a custom_type.", "example": "12345", "nullable": true }, "custom_type_status_option": { "type": "string", "readOnly": false, "x-env-variable": true, "description": "GID or globally-unique identifier of a custom_type_status_option", "example": "12345", "nullable": true } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created the specified subtask.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "properties": { "approval_status": { "type": "string", "description": "*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.", "enum": [ "pending", "approved", "rejected", "changes_requested" ], "example": "pending" }, "assignee_status": { "description": "*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to \"inbox\" or \"upcoming\" inserts it at the top of the section, while the other options will insert at the bottom.", "type": "string", "enum": [ "today", "upcoming", "later", "new", "inbox" ], "example": "upcoming" }, "completed": { "description": "True if the task is currently marked complete, false if not.", "type": "boolean", "example": false }, "completed_at": { "description": "The time at which this task was completed, or null if the task is incomplete.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "readOnly": true, "nullable": true } ] }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "dependencies": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "dependents": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.147Z", "nullable": true }, "due_on": { "description": "The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.", "type": "string", "format": "date", "example": "2019-09-15", "nullable": true }, "external": { "description": "*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).\nThe external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.", "type": "object", "properties": { "gid": { "type": "string", "example": "1234" }, "data": { "type": "string", "example": "A blob of information." } }, "example": { "gid": "my_gid", "data": "A blob of information" } }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "hearted": { "description": "*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "is_rendered_as_separator": { "description": "[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`. This parameter only applies to regular tasks with `resource_subtype` of `default_task`. Tasks with `resource_subtype` of `milestone`, `approval`, or custom task types will not have this property and cannot be rendered as separators.", "type": "boolean", "example": false, "readOnly": true }, "liked": { "description": "True if the task is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "memberships": { "description": "

Full object requires scope: projects:read, project_sections:read

\n\n*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.", "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } } } } }, "modified_at": { "description": "The time at which this task was last modified.\n\nThe following conditions will change `modified_at`:\n\n- story is created on a task\n- story is trashed on a task\n- attachment is trashed on a task\n- task is assigned or unassigned\n- custom field value is changed\n- the task itself is trashed\n- Or if any of the following fields are updated:\n - completed\n - name\n - due_date\n - description\n - attachments\n - items\n - schedule_status\n\nThe following conditions will _not_ change `modified_at`:\n\n- moving to a new container (project, portfolio, etc)\n- comments being added to the task (but the stories they generate\n _will_ affect `modified_at`)", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "name": { "description": "Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Buy catnip" }, "notes": { "description": "Free-form textual information associated with the task (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this task.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this task.", "type": "integer", "example": 5, "readOnly": true }, "num_subtasks": { "description": "[Opt In](/docs/inputoutput-options). The number of subtasks on this task.\n", "type": "integer", "example": 3, "readOnly": true }, "start_at": { "description": "Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.\n*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*", "type": "string", "nullable": true, "format": "date-time", "example": "2019-09-14T02:06:58.147Z" }, "start_on": { "description": "The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.\n*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "actual_time_minutes": { "description": "

Full object requires scope: time_tracking_entries:read

\n\nThis value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.", "type": "number", "example": 200, "readOnly": true, "nullable": true } } } ] }, { "type": "object", "properties": { "assignee": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "assignee_section": { "allOf": [ { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, { "type": "object", "nullable": true, "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list." } ] }, "custom_fields": { "description": "Array of custom field values applied to the task. These represent the custom field values recorded on this project for a particular custom field. For example, these custom field values will contain an `enum_value` property for custom fields of type `enum`, a `text_value` property for custom fields of type `text`, and so on. Please note that the `gid` returned on each custom field value *is identical* to the `gid` of the custom field, which allows referencing the custom field metadata through the `/custom_fields/custom_field_gid` endpoint.", "type": "array", "items": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, "readOnly": true }, "custom_type": { "allOf": [ { "description": "Custom Types extend the types of Asana Objects, currently only Custom Tasks are supported.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type.", "example": "Bug ticket" } } }, { "nullable": true } ] }, "custom_type_status_option": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type_status_option", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type status option.", "example": "Solution pending" } } }, { "nullable": true } ] }, "followers": { "description": "Array of users following this task.", "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "parent": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "readOnly": true, "description": "The parent of this task, or `null` if this is not a subtask. This property cannot be modified using a PUT request but you can change it with the `setParent` endpoint. You can create subtasks by using the subtasks endpoint.", "nullable": true } ] }, "projects": { "description": "*Create-only.* Array of projects this task is associated with. At task creation time, this array can be used to add the task to many projects at once. After task creation, these associations can be modified using the addProject and removeProject endpoints.", "type": "array", "readOnly": true, "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "tags": { "description": "Array of tags associated with this task. In order to change tags on an existing task use `addTag` and `removeTag`.", "type": "array", "readOnly": true, "items": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "example": [ { "gid": "59746", "name": "Grade A" } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace this task is associated with. Once created, task cannot be moved to a different workspace. This attribute can only be specified at creation time." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/task/123456789" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTask result = client.tasks.createSubtaskForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The new subtask to create.\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\"\n};\ntasksApiInstance.createSubtaskForTask(body, task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.createSubtaskForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The new subtask to create.\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a subtask\n api_response = tasks_api_instance.create_subtask_for_task(body, task_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->create_subtask_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.create_subtask_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->createSubtaskForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.create_subtask_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 58, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/setParent": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Set the parent of a task", "description": "Required scope: tasks:write\n\nUpdates the parent of a given task. This endpoint can be used to make a task a subtask of another task, or to remove its existing parent.\nWhen using `insert_before` and `insert_after`, at most one of those two options can be specified, and they must already be subtasks of the parent.\nReturns the complete, updated record of the affected [task](/reference/tasks#/task).", "tags": [ "Tasks" ], "operationId": "setParentForTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The new parent of the subtask.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "parent": { "description": "The new parent of the task, or `null` for no parent.", "type": "string", "example": "987654" }, "insert_after": { "description": "A subtask of the parent to insert the task after, or `null` to insert at the beginning of the list.", "type": "string", "example": "null" }, "insert_before": { "description": "A subtask of the parent to insert the task before, or `null` to insert at the end of the list.", "type": "string", "example": "124816" } }, "required": [ "parent" ] } } } } } }, "responses": { "200": { "description": "Successfully changed the parent of the specified subtask.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "properties": { "approval_status": { "type": "string", "description": "*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.", "enum": [ "pending", "approved", "rejected", "changes_requested" ], "example": "pending" }, "assignee_status": { "description": "*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to \"inbox\" or \"upcoming\" inserts it at the top of the section, while the other options will insert at the bottom.", "type": "string", "enum": [ "today", "upcoming", "later", "new", "inbox" ], "example": "upcoming" }, "completed": { "description": "True if the task is currently marked complete, false if not.", "type": "boolean", "example": false }, "completed_at": { "description": "The time at which this task was completed, or null if the task is incomplete.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "readOnly": true, "nullable": true } ] }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "dependencies": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "dependents": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.147Z", "nullable": true }, "due_on": { "description": "The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.", "type": "string", "format": "date", "example": "2019-09-15", "nullable": true }, "external": { "description": "*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).\nThe external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.", "type": "object", "properties": { "gid": { "type": "string", "example": "1234" }, "data": { "type": "string", "example": "A blob of information." } }, "example": { "gid": "my_gid", "data": "A blob of information" } }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "hearted": { "description": "*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "is_rendered_as_separator": { "description": "[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`. This parameter only applies to regular tasks with `resource_subtype` of `default_task`. Tasks with `resource_subtype` of `milestone`, `approval`, or custom task types will not have this property and cannot be rendered as separators.", "type": "boolean", "example": false, "readOnly": true }, "liked": { "description": "True if the task is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "memberships": { "description": "

Full object requires scope: projects:read, project_sections:read

\n\n*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.", "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } } } } }, "modified_at": { "description": "The time at which this task was last modified.\n\nThe following conditions will change `modified_at`:\n\n- story is created on a task\n- story is trashed on a task\n- attachment is trashed on a task\n- task is assigned or unassigned\n- custom field value is changed\n- the task itself is trashed\n- Or if any of the following fields are updated:\n - completed\n - name\n - due_date\n - description\n - attachments\n - items\n - schedule_status\n\nThe following conditions will _not_ change `modified_at`:\n\n- moving to a new container (project, portfolio, etc)\n- comments being added to the task (but the stories they generate\n _will_ affect `modified_at`)", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "name": { "description": "Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Buy catnip" }, "notes": { "description": "Free-form textual information associated with the task (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this task.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this task.", "type": "integer", "example": 5, "readOnly": true }, "num_subtasks": { "description": "[Opt In](/docs/inputoutput-options). The number of subtasks on this task.\n", "type": "integer", "example": 3, "readOnly": true }, "start_at": { "description": "Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.\n*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*", "type": "string", "nullable": true, "format": "date-time", "example": "2019-09-14T02:06:58.147Z" }, "start_on": { "description": "The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.\n*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "actual_time_minutes": { "description": "

Full object requires scope: time_tracking_entries:read

\n\nThis value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.", "type": "number", "example": 200, "readOnly": true, "nullable": true } } } ] }, { "type": "object", "properties": { "assignee": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "assignee_section": { "allOf": [ { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, { "type": "object", "nullable": true, "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list." } ] }, "custom_fields": { "description": "Array of custom field values applied to the task. These represent the custom field values recorded on this project for a particular custom field. For example, these custom field values will contain an `enum_value` property for custom fields of type `enum`, a `text_value` property for custom fields of type `text`, and so on. Please note that the `gid` returned on each custom field value *is identical* to the `gid` of the custom field, which allows referencing the custom field metadata through the `/custom_fields/custom_field_gid` endpoint.", "type": "array", "items": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, "readOnly": true }, "custom_type": { "allOf": [ { "description": "Custom Types extend the types of Asana Objects, currently only Custom Tasks are supported.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type.", "example": "Bug ticket" } } }, { "nullable": true } ] }, "custom_type_status_option": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type_status_option", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type status option.", "example": "Solution pending" } } }, { "nullable": true } ] }, "followers": { "description": "Array of users following this task.", "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "parent": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "readOnly": true, "description": "The parent of this task, or `null` if this is not a subtask. This property cannot be modified using a PUT request but you can change it with the `setParent` endpoint. You can create subtasks by using the subtasks endpoint.", "nullable": true } ] }, "projects": { "description": "*Create-only.* Array of projects this task is associated with. At task creation time, this array can be used to add the task to many projects at once. After task creation, these associations can be modified using the addProject and removeProject endpoints.", "type": "array", "readOnly": true, "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "tags": { "description": "Array of tags associated with this task. In order to change tags on an existing task use `addTag` and `removeTag`.", "type": "array", "readOnly": true, "items": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "example": [ { "gid": "59746", "name": "Grade A" } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace this task is associated with. Once created, task cannot be moved to a different workspace. This attribute can only be specified at creation time." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/task/123456789" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTask result = client.tasks.setParentForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The new parent of the subtask.\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\"\n};\ntasksApiInstance.setParentForTask(body, task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.setParentForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The new parent of the subtask.\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Set the parent of a task\n api_response = tasks_api_instance.set_parent_for_task(body, task_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->set_parent_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.set_parent_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->setParentForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.set_parent_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 3, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/dependencies": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get dependencies from a task", "description": "Required scope: tasks:read\n\nReturns the compact representations of all of the dependencies of a task.", "tags": [ "Tasks" ], "operationId": "getDependenciesForTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified task's dependencies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.tasks.getDependenciesForTask(taskGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\"\n};\ntasksApiInstance.getDependenciesForTask(task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.getDependenciesForTask(taskGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get dependencies from a task\n api_response = tasks_api_instance.get_dependencies_for_task(task_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->get_dependencies_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.get_dependencies_for_task(task_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->getDependenciesForTask($task_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.get_dependencies_for_task(task_gid: 'task_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/addDependencies": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Set dependencies for a task", "description": "Required scope: tasks:write\n\nMarks a set of tasks as dependencies of this task, if they are not already dependencies. *A task can have at most 30 dependents and dependencies combined*.", "tags": [ "Tasks" ], "operationId": "addDependenciesForTask", "requestBody": { "description": "The list of tasks to set as dependencies.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dependencies": { "description": "An array of task gids that a task depends on.", "type": "array", "items": { "type": "string" } } }, "example": { "dependencies": [ "133713", "184253" ] } } } } } } }, "responses": { "200": { "description": "Successfully set the specified dependencies on the task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.tasks.addDependenciesForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The list of tasks to set as dependencies.\nlet task_gid = \"321654\"; // String | The task to operate on.\n\ntasksApiInstance.addDependenciesForTask(body, task_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.addDependenciesForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The list of tasks to set as dependencies.\ntask_gid = \"321654\" # str | The task to operate on.\n\n\ntry:\n # Set dependencies for a task\n api_response = tasks_api_instance.add_dependencies_for_task(body, task_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->add_dependencies_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.add_dependencies_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->addDependenciesForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.add_dependencies_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/removeDependencies": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Unlink dependencies from a task", "description": "Required scope: tasks:write\n\nUnlinks a set of dependencies from this task.", "tags": [ "Tasks" ], "operationId": "removeDependenciesForTask", "requestBody": { "description": "The list of tasks to unlink as dependencies.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dependencies": { "description": "An array of task gids that a task depends on.", "type": "array", "items": { "type": "string" } } }, "example": { "dependencies": [ "133713", "184253" ] } } } } } } }, "responses": { "200": { "description": "Successfully unlinked the dependencies from the specified task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.tasks.removeDependenciesForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The list of tasks to unlink as dependencies.\nlet task_gid = \"321654\"; // String | The task to operate on.\n\ntasksApiInstance.removeDependenciesForTask(body, task_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.removeDependenciesForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The list of tasks to unlink as dependencies.\ntask_gid = \"321654\" # str | The task to operate on.\n\n\ntry:\n # Unlink dependencies from a task\n api_response = tasks_api_instance.remove_dependencies_for_task(body, task_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->remove_dependencies_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.remove_dependencies_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->removeDependenciesForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.remove_dependencies_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/dependents": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get dependents from a task", "description": "Required scope: tasks:read\n\nReturns the compact representations of all of the dependents of a task.", "tags": [ "Tasks" ], "operationId": "getDependentsForTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "offset", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "path", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "uri", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the specified dependents of the task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.tasks.getDependentsForTask(taskGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\"\n};\ntasksApiInstance.getDependentsForTask(task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.getDependentsForTask(taskGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,offset,parent,parent.created_by,parent.name,parent.resource_subtype,path,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,uri,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get dependents from a task\n api_response = tasks_api_instance.get_dependents_for_task(task_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->get_dependents_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.get_dependents_for_task(task_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->getDependentsForTask($task_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.get_dependents_for_task(task_gid: 'task_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/addDependents": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Set dependents for a task", "description": "Required scope: tasks:write\n\nMarks a set of tasks as dependents of this task, if they are not already dependents. *A task can have at most 30 dependents and dependencies combined*.", "tags": [ "Tasks" ], "operationId": "addDependentsForTask", "requestBody": { "description": "The list of tasks to add as dependents.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A set of dependent tasks.", "type": "object", "properties": { "dependents": { "description": "An array of task gids that are dependents of the given task.", "type": "array", "items": { "type": "string" } } }, "example": { "dependents": [ "133713", "184253" ] } } } } } } }, "responses": { "200": { "description": "Successfully set the specified dependents on the given task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.tasks.addDependentsForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The list of tasks to add as dependents.\nlet task_gid = \"321654\"; // String | The task to operate on.\n\ntasksApiInstance.addDependentsForTask(body, task_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.addDependentsForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The list of tasks to add as dependents.\ntask_gid = \"321654\" # str | The task to operate on.\n\n\ntry:\n # Set dependents for a task\n api_response = tasks_api_instance.add_dependents_for_task(body, task_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->add_dependents_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.add_dependents_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->addDependentsForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.add_dependents_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/removeDependents": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Unlink dependents from a task", "description": "Required scope: tasks:write\n\nUnlinks a set of dependents from this task.", "tags": [ "Tasks" ], "operationId": "removeDependentsForTask", "requestBody": { "description": "The list of tasks to remove as dependents.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A set of dependent tasks.", "type": "object", "properties": { "dependents": { "description": "An array of task gids that are dependents of the given task.", "type": "array", "items": { "type": "string" } } }, "example": { "dependents": [ "133713", "184253" ] } } } } } } }, "responses": { "200": { "description": "Successfully unlinked the specified tasks as dependents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.tasks.removeDependentsForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The list of tasks to remove as dependents.\nlet task_gid = \"321654\"; // String | The task to operate on.\n\ntasksApiInstance.removeDependentsForTask(body, task_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.removeDependentsForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The list of tasks to remove as dependents.\ntask_gid = \"321654\" # str | The task to operate on.\n\n\ntry:\n # Unlink dependents from a task\n api_response = tasks_api_instance.remove_dependents_for_task(body, task_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->remove_dependents_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.remove_dependents_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->removeDependentsForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.remove_dependents_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/addProject": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add a project to a task", "description": "Required scope: tasks:write\n\nAdds the task to the specified project, in the optional location\nspecified. If no location arguments are given, the task will be added to\nthe end of the project.\n\n`addProject` can also be used to reorder a task within a project or\nsection that already contains it.\n\nAt most one of `insert_before`, `insert_after`, or `section` should be\nspecified. Inserting into a section in an non-order-dependent way can be\ndone by specifying section, otherwise, to insert within a section in a\nparticular place, specify `insert_before` or `insert_after` and a task\nwithin the section to anchor the position of this task.\n\nA task can have at most 20 projects multi-homed to it.\n\nReturns an empty data block.", "tags": [ "Tasks" ], "operationId": "addProjectForTask", "requestBody": { "description": "The project to add the task to.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "project": { "description": "The project to add the task to.", "type": "string", "example": "13579" }, "insert_after": { "description": "A task in the project to insert the task after, or `null` to insert at the beginning of the list.", "type": "string", "nullable": true, "example": "124816" }, "insert_before": { "description": "A task in the project to insert the task before, or `null` to insert at the end of the list.", "type": "string", "nullable": true, "example": "432134" }, "section": { "description": "A section in the project to insert the task into. The task will be inserted at the bottom of the section.", "type": "string", "nullable": true, "example": "987654" } }, "required": [ "project" ] } } } } } }, "responses": { "200": { "description": "Successfully added the specified project to the task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.tasks.addProjectForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The project to add the task to.\nlet task_gid = \"321654\"; // String | The task to operate on.\n\ntasksApiInstance.addProjectForTask(body, task_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.addProjectForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The project to add the task to.\ntask_gid = \"321654\" # str | The task to operate on.\n\n\ntry:\n # Add a project to a task\n api_response = tasks_api_instance.add_project_for_task(body, task_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->add_project_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.add_project_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->addProjectForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.add_project_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 4, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/removeProject": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Remove a project from a task", "description": "Required scope: tasks:write\n\nRemoves the task from the specified project. The task will still exist in\nthe system, but it will not be in the project anymore.\n\nReturns an empty data block.", "tags": [ "Tasks" ], "operationId": "removeProjectForTask", "requestBody": { "description": "The project to remove the task from.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "project": { "description": "The project to remove the task from.", "type": "string", "example": "13579" } }, "required": [ "project" ] } } } } } }, "responses": { "200": { "description": "Successfully removed the specified project from the task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.tasks.removeProjectForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The project to remove the task from.\nlet task_gid = \"321654\"; // String | The task to operate on.\n\ntasksApiInstance.removeProjectForTask(body, task_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.removeProjectForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The project to remove the task from.\ntask_gid = \"321654\" # str | The task to operate on.\n\n\ntry:\n # Remove a project from a task\n api_response = tasks_api_instance.remove_project_for_task(body, task_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->remove_project_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.remove_project_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->removeProjectForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.remove_project_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/addTag": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add a tag to a task", "description": "Required scope: tasks:write\n\nAdds a tag to a task. Returns an empty data block.", "tags": [ "Tasks" ], "operationId": "addTagForTask", "requestBody": { "description": "The tag to add to the task.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tag": { "description": "The tag's gid to add to the task.", "type": "string", "example": "13579" } }, "required": [ "tag" ] } } } } } }, "responses": { "200": { "description": "Successfully added the specified tag to the task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.tasks.addTagForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The tag to add to the task.\nlet task_gid = \"321654\"; // String | The task to operate on.\n\ntasksApiInstance.addTagForTask(body, task_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.addTagForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The tag to add to the task.\ntask_gid = \"321654\" # str | The task to operate on.\n\n\ntry:\n # Add a tag to a task\n api_response = tasks_api_instance.add_tag_for_task(body, task_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->add_tag_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.add_tag_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->addTagForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.add_tag_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/removeTag": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Remove a tag from a task", "description": "Required scope: tasks:write\n\nRemoves a tag from a task. Returns an empty data block.", "tags": [ "Tasks" ], "operationId": "removeTagForTask", "requestBody": { "description": "The tag to remove from the task.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tag": { "description": "The tag's gid to remove from the task.", "type": "string", "example": "13579" } }, "required": [ "tag" ] } } } } } }, "responses": { "200": { "description": "Successfully removed the specified tag from the task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.tasks.removeTagForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The tag to remove from the task.\nlet task_gid = \"321654\"; // String | The task to operate on.\n\ntasksApiInstance.removeTagForTask(body, task_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.removeTagForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The tag to remove from the task.\ntask_gid = \"321654\" # str | The task to operate on.\n\n\ntry:\n # Remove a tag from a task\n api_response = tasks_api_instance.remove_tag_for_task(body, task_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->remove_tag_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.remove_tag_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->removeTagForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.remove_tag_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/addFollowers": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add followers to a task", "description": "Required scope: tasks:write\n\nAdds followers to a task. Returns an empty data block.\nEach task can be associated with zero or more followers in the system.\nRequests to add/remove followers, if successful, will return the complete updated task record, described above.", "tags": [ "Tasks" ], "operationId": "addFollowersForTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The followers to add to the task.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "followers": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "array", "items": { "type": "string" }, "example": [ "13579", "321654" ] } }, "required": [ "followers" ] } } } } } }, "responses": { "200": { "description": "Successfully added the specified followers to the task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "properties": { "approval_status": { "type": "string", "description": "*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.", "enum": [ "pending", "approved", "rejected", "changes_requested" ], "example": "pending" }, "assignee_status": { "description": "*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to \"inbox\" or \"upcoming\" inserts it at the top of the section, while the other options will insert at the bottom.", "type": "string", "enum": [ "today", "upcoming", "later", "new", "inbox" ], "example": "upcoming" }, "completed": { "description": "True if the task is currently marked complete, false if not.", "type": "boolean", "example": false }, "completed_at": { "description": "The time at which this task was completed, or null if the task is incomplete.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "readOnly": true, "nullable": true } ] }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "dependencies": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "dependents": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.147Z", "nullable": true }, "due_on": { "description": "The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.", "type": "string", "format": "date", "example": "2019-09-15", "nullable": true }, "external": { "description": "*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).\nThe external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.", "type": "object", "properties": { "gid": { "type": "string", "example": "1234" }, "data": { "type": "string", "example": "A blob of information." } }, "example": { "gid": "my_gid", "data": "A blob of information" } }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "hearted": { "description": "*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "is_rendered_as_separator": { "description": "[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`. This parameter only applies to regular tasks with `resource_subtype` of `default_task`. Tasks with `resource_subtype` of `milestone`, `approval`, or custom task types will not have this property and cannot be rendered as separators.", "type": "boolean", "example": false, "readOnly": true }, "liked": { "description": "True if the task is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "memberships": { "description": "

Full object requires scope: projects:read, project_sections:read

\n\n*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.", "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } } } } }, "modified_at": { "description": "The time at which this task was last modified.\n\nThe following conditions will change `modified_at`:\n\n- story is created on a task\n- story is trashed on a task\n- attachment is trashed on a task\n- task is assigned or unassigned\n- custom field value is changed\n- the task itself is trashed\n- Or if any of the following fields are updated:\n - completed\n - name\n - due_date\n - description\n - attachments\n - items\n - schedule_status\n\nThe following conditions will _not_ change `modified_at`:\n\n- moving to a new container (project, portfolio, etc)\n- comments being added to the task (but the stories they generate\n _will_ affect `modified_at`)", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "name": { "description": "Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Buy catnip" }, "notes": { "description": "Free-form textual information associated with the task (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this task.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this task.", "type": "integer", "example": 5, "readOnly": true }, "num_subtasks": { "description": "[Opt In](/docs/inputoutput-options). The number of subtasks on this task.\n", "type": "integer", "example": 3, "readOnly": true }, "start_at": { "description": "Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.\n*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*", "type": "string", "nullable": true, "format": "date-time", "example": "2019-09-14T02:06:58.147Z" }, "start_on": { "description": "The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.\n*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "actual_time_minutes": { "description": "

Full object requires scope: time_tracking_entries:read

\n\nThis value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.", "type": "number", "example": 200, "readOnly": true, "nullable": true } } } ] }, { "type": "object", "properties": { "assignee": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "assignee_section": { "allOf": [ { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, { "type": "object", "nullable": true, "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list." } ] }, "custom_fields": { "description": "Array of custom field values applied to the task. These represent the custom field values recorded on this project for a particular custom field. For example, these custom field values will contain an `enum_value` property for custom fields of type `enum`, a `text_value` property for custom fields of type `text`, and so on. Please note that the `gid` returned on each custom field value *is identical* to the `gid` of the custom field, which allows referencing the custom field metadata through the `/custom_fields/custom_field_gid` endpoint.", "type": "array", "items": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, "readOnly": true }, "custom_type": { "allOf": [ { "description": "Custom Types extend the types of Asana Objects, currently only Custom Tasks are supported.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type.", "example": "Bug ticket" } } }, { "nullable": true } ] }, "custom_type_status_option": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type_status_option", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type status option.", "example": "Solution pending" } } }, { "nullable": true } ] }, "followers": { "description": "Array of users following this task.", "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "parent": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "readOnly": true, "description": "The parent of this task, or `null` if this is not a subtask. This property cannot be modified using a PUT request but you can change it with the `setParent` endpoint. You can create subtasks by using the subtasks endpoint.", "nullable": true } ] }, "projects": { "description": "*Create-only.* Array of projects this task is associated with. At task creation time, this array can be used to add the task to many projects at once. After task creation, these associations can be modified using the addProject and removeProject endpoints.", "type": "array", "readOnly": true, "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "tags": { "description": "Array of tags associated with this task. In order to change tags on an existing task use `addTag` and `removeTag`.", "type": "array", "readOnly": true, "items": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "example": [ { "gid": "59746", "name": "Grade A" } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace this task is associated with. Once created, task cannot be moved to a different workspace. This attribute can only be specified at creation time." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/task/123456789" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTask result = client.tasks.addFollowersForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The followers to add to the task.\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\"\n};\ntasksApiInstance.addFollowersForTask(body, task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.addFollowersForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The followers to add to the task.\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Add followers to a task\n api_response = tasks_api_instance.add_followers_for_task(body, task_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->add_followers_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.add_followers_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->addFollowersForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.add_followers_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/removeFollowers": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Remove followers from a task", "description": "Required scope: tasks:write\n\nRemoves each of the specified followers from the task if they are following. Returns the complete, updated record for the affected task.", "tags": [ "Tasks" ], "operationId": "removeFollowerForTask", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The followers to remove from the task.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "followers": { "description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user.", "type": "array", "items": { "type": "string" }, "example": [ "13579", "321654" ] } }, "required": [ "followers" ] } } } } } }, "responses": { "200": { "description": "Successfully removed the specified followers from the task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "properties": { "approval_status": { "type": "string", "description": "*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.", "enum": [ "pending", "approved", "rejected", "changes_requested" ], "example": "pending" }, "assignee_status": { "description": "*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to \"inbox\" or \"upcoming\" inserts it at the top of the section, while the other options will insert at the bottom.", "type": "string", "enum": [ "today", "upcoming", "later", "new", "inbox" ], "example": "upcoming" }, "completed": { "description": "True if the task is currently marked complete, false if not.", "type": "boolean", "example": false }, "completed_at": { "description": "The time at which this task was completed, or null if the task is incomplete.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "readOnly": true, "nullable": true } ] }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "dependencies": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "dependents": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.147Z", "nullable": true }, "due_on": { "description": "The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.", "type": "string", "format": "date", "example": "2019-09-15", "nullable": true }, "external": { "description": "*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).\nThe external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.", "type": "object", "properties": { "gid": { "type": "string", "example": "1234" }, "data": { "type": "string", "example": "A blob of information." } }, "example": { "gid": "my_gid", "data": "A blob of information" } }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "hearted": { "description": "*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "is_rendered_as_separator": { "description": "[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`. This parameter only applies to regular tasks with `resource_subtype` of `default_task`. Tasks with `resource_subtype` of `milestone`, `approval`, or custom task types will not have this property and cannot be rendered as separators.", "type": "boolean", "example": false, "readOnly": true }, "liked": { "description": "True if the task is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "memberships": { "description": "

Full object requires scope: projects:read, project_sections:read

\n\n*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.", "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } } } } }, "modified_at": { "description": "The time at which this task was last modified.\n\nThe following conditions will change `modified_at`:\n\n- story is created on a task\n- story is trashed on a task\n- attachment is trashed on a task\n- task is assigned or unassigned\n- custom field value is changed\n- the task itself is trashed\n- Or if any of the following fields are updated:\n - completed\n - name\n - due_date\n - description\n - attachments\n - items\n - schedule_status\n\nThe following conditions will _not_ change `modified_at`:\n\n- moving to a new container (project, portfolio, etc)\n- comments being added to the task (but the stories they generate\n _will_ affect `modified_at`)", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "name": { "description": "Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Buy catnip" }, "notes": { "description": "Free-form textual information associated with the task (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this task.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this task.", "type": "integer", "example": 5, "readOnly": true }, "num_subtasks": { "description": "[Opt In](/docs/inputoutput-options). The number of subtasks on this task.\n", "type": "integer", "example": 3, "readOnly": true }, "start_at": { "description": "Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.\n*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*", "type": "string", "nullable": true, "format": "date-time", "example": "2019-09-14T02:06:58.147Z" }, "start_on": { "description": "The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.\n*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "actual_time_minutes": { "description": "

Full object requires scope: time_tracking_entries:read

\n\nThis value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.", "type": "number", "example": 200, "readOnly": true, "nullable": true } } } ] }, { "type": "object", "properties": { "assignee": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "assignee_section": { "allOf": [ { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, { "type": "object", "nullable": true, "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list." } ] }, "custom_fields": { "description": "Array of custom field values applied to the task. These represent the custom field values recorded on this project for a particular custom field. For example, these custom field values will contain an `enum_value` property for custom fields of type `enum`, a `text_value` property for custom fields of type `text`, and so on. Please note that the `gid` returned on each custom field value *is identical* to the `gid` of the custom field, which allows referencing the custom field metadata through the `/custom_fields/custom_field_gid` endpoint.", "type": "array", "items": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, "readOnly": true }, "custom_type": { "allOf": [ { "description": "Custom Types extend the types of Asana Objects, currently only Custom Tasks are supported.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type.", "example": "Bug ticket" } } }, { "nullable": true } ] }, "custom_type_status_option": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type_status_option", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type status option.", "example": "Solution pending" } } }, { "nullable": true } ] }, "followers": { "description": "Array of users following this task.", "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "parent": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "readOnly": true, "description": "The parent of this task, or `null` if this is not a subtask. This property cannot be modified using a PUT request but you can change it with the `setParent` endpoint. You can create subtasks by using the subtasks endpoint.", "nullable": true } ] }, "projects": { "description": "*Create-only.* Array of projects this task is associated with. At task creation time, this array can be used to add the task to many projects at once. After task creation, these associations can be modified using the addProject and removeProject endpoints.", "type": "array", "readOnly": true, "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "tags": { "description": "Array of tags associated with this task. In order to change tags on an existing task use `addTag` and `removeTag`.", "type": "array", "readOnly": true, "items": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "example": [ { "gid": "59746", "name": "Grade A" } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace this task is associated with. Once created, task cannot be moved to a different workspace. This attribute can only be specified at creation time." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/task/123456789" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTask result = client.tasks.removeFollowerForTask(taskGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The followers to remove from the task.\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\"\n};\ntasksApiInstance.removeFollowerForTask(body, task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.removeFollowerForTask(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The followers to remove from the task.\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Remove followers from a task\n api_response = tasks_api_instance.remove_follower_for_task(body, task_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->remove_follower_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.remove_follower_for_task(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->removeFollowerForTask($task_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.remove_follower_for_task(task_gid: 'task_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/tasks/custom_id/{custom_id}": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "custom_id", "in": "path", "description": "Generated custom ID for a task.", "required": true, "schema": { "type": "string" }, "example": "EX-1" } ], "get": { "summary": "Get a task for a given custom ID", "description": "Required scope: tasks:read\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
FieldRequired Scope
membershipsprojects:read, project_sections:read
actual_time_minutestime_tracking_entries:read
\n\nReturns a task given a custom ID shortcode.", "tags": [ "Tasks" ], "operationId": "getTaskForCustomID", "security": [ { "oauth2": [ "tasks:read" ] } ], "responses": { "200": { "description": "Successfully retrieved task for given custom ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "properties": { "approval_status": { "type": "string", "description": "*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.", "enum": [ "pending", "approved", "rejected", "changes_requested" ], "example": "pending" }, "assignee_status": { "description": "*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to \"inbox\" or \"upcoming\" inserts it at the top of the section, while the other options will insert at the bottom.", "type": "string", "enum": [ "today", "upcoming", "later", "new", "inbox" ], "example": "upcoming" }, "completed": { "description": "True if the task is currently marked complete, false if not.", "type": "boolean", "example": false }, "completed_at": { "description": "The time at which this task was completed, or null if the task is incomplete.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2012-02-22T02:06:58.147Z" }, "completed_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "readOnly": true, "nullable": true } ] }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "dependencies": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "dependents": { "description": "[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" } } }, "readOnly": true }, "due_at": { "description": "The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.", "type": "string", "format": "date-time", "example": "2019-09-15T02:06:58.147Z", "nullable": true }, "due_on": { "description": "The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.", "type": "string", "format": "date", "example": "2019-09-15", "nullable": true }, "external": { "description": "*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).\nThe external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.", "type": "object", "properties": { "gid": { "type": "string", "example": "1234" }, "data": { "type": "string", "example": "A blob of information." } }, "example": { "gid": "my_gid", "data": "A blob of information" } }, "html_notes": { "description": "[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "hearted": { "description": "*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.", "type": "boolean", "example": true, "readOnly": true }, "hearts": { "description": "*Deprecated - please use likes instead* Array of likes for users who have hearted this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "is_rendered_as_separator": { "description": "[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`. This parameter only applies to regular tasks with `resource_subtype` of `default_task`. Tasks with `resource_subtype` of `milestone`, `approval`, or custom task types will not have this property and cannot be rendered as separators.", "type": "boolean", "example": false, "readOnly": true }, "liked": { "description": "True if the task is liked by the authorized user, false if not.", "type": "boolean", "example": true }, "likes": { "description": "Array of likes for users who have liked this task.", "type": "array", "items": { "type": "object", "description": "An object to represent a user's like.", "properties": { "gid": { "description": "Globally unique identifier of the object, as a string.", "type": "string", "readOnly": true, "example": "12345" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, "readOnly": true }, "memberships": { "description": "

Full object requires scope: projects:read, project_sections:read

\n\n*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.", "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "project": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "section": { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } } } } }, "modified_at": { "description": "The time at which this task was last modified.\n\nThe following conditions will change `modified_at`:\n\n- story is created on a task\n- story is trashed on a task\n- attachment is trashed on a task\n- task is assigned or unassigned\n- custom field value is changed\n- the task itself is trashed\n- Or if any of the following fields are updated:\n - completed\n - name\n - due_date\n - description\n - attachments\n - items\n - schedule_status\n\nThe following conditions will _not_ change `modified_at`:\n\n- moving to a new container (project, portfolio, etc)\n- comments being added to the task (but the stories they generate\n _will_ affect `modified_at`)", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "name": { "description": "Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Buy catnip" }, "notes": { "description": "Free-form textual information associated with the task (i.e. its description).", "type": "string", "example": "Mittens really likes the stuff from Humboldt." }, "num_hearts": { "description": "*Deprecated - please use likes instead* The number of users who have hearted this task.", "type": "integer", "example": 5, "readOnly": true }, "num_likes": { "description": "The number of users who have liked this task.", "type": "integer", "example": 5, "readOnly": true }, "num_subtasks": { "description": "[Opt In](/docs/inputoutput-options). The number of subtasks on this task.\n", "type": "integer", "example": 3, "readOnly": true }, "start_at": { "description": "Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.\n*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*", "type": "string", "nullable": true, "format": "date-time", "example": "2019-09-14T02:06:58.147Z" }, "start_on": { "description": "The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.\n*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*", "type": "string", "nullable": true, "format": "date", "example": "2019-09-14" }, "actual_time_minutes": { "description": "

Full object requires scope: time_tracking_entries:read

\n\nThis value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.", "type": "number", "example": 200, "readOnly": true, "nullable": true } } } ] }, { "type": "object", "properties": { "assignee": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "assignee_section": { "allOf": [ { "description": "A *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "section", "x-insert-after": "gid" }, "name": { "description": "The name of the section (i.e. the text displayed as the section header).", "type": "string", "example": "Next Actions" } } }, { "type": "object", "nullable": true, "description": "The *assignee section* is a subdivision of a project that groups tasks together in the assignee's \"My tasks\" list. It can either be a header above a list of tasks in a list view or a column in a board view of \"My tasks.\"\nThe `assignee_section` property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to `assignee_section` with the gid of an existing section visible in the user's \"My tasks\" list." } ] }, "custom_fields": { "description": "Array of custom field values applied to the task. These represent the custom field values recorded on this project for a particular custom field. For example, these custom field values will contain an `enum_value` property for custom fields of type `enum`, a `text_value` property for custom fields of type `text`, and so on. Please note that the `gid` returned on each custom field value *is identical* to the `gid` of the custom field, which allows referencing the custom field metadata through the `/custom_fields/custom_field_gid` endpoint.", "type": "array", "items": { "allOf": [ { "allOf": [ { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the custom field.", "type": "string", "example": "Development team priority" }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "precision": { "description": "Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0.", "type": "integer", "example": 2 }, "format": { "description": "The format of this custom field.", "type": "string", "enum": [ "currency", "identifier", "percentage", "custom", "duration", "none" ], "example": "custom" }, "currency_code": { "description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.", "type": "string", "nullable": true, "example": "EUR" }, "custom_label": { "description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "example": "gold pieces" }, "custom_label_position": { "description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.", "type": "string", "nullable": true, "enum": [ "prefix", "suffix", null ], "example": "suffix" }, "is_global_to_workspace": { "description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.", "type": "boolean", "example": true, "readOnly": true }, "has_notifications_enabled": { "description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.", "type": "boolean", "example": true }, "asana_created_field": { "description": "*Conditional*. A unique identifier to associate this field with the template source of truth.", "type": "string", "readOnly": true, "nullable": true, "enum": [ "a_v_requirements", "account_name", "actionable", "align_shipping_link", "align_status", "allotted_time", "appointment", "approval_stage", "approved", "article_series", "board_committee", "browser", "campaign_audience", "campaign_project_status", "campaign_regions", "channel_primary", "client_topic_type", "complete_by", "contact", "contact_email_address", "content_channels", "content_channels_needed", "content_stage", "content_type", "contract", "contract_status", "cost", "creation_stage", "creative_channel", "creative_needed", "creative_needs", "data_sensitivity", "deal_size", "delivery_appt", "delivery_appt_date", "department", "department_responsible", "design_request_needed", "design_request_type", "discussion_category", "do_this_task", "editorial_content_status", "editorial_content_tag", "editorial_content_type", "effort", "effort_level", "est_completion_date", "estimated_time", "estimated_value", "expected_cost", "external_steps_needed", "favorite_idea", "feedback_type", "financial", "funding_amount", "grant_application_process", "hiring_candidate_status", "idea_status", "ids_link", "ids_patient_link", "implementation_stage", "insurance", "interview_area", "interview_question_score", "itero_scan_link", "job_s_applied_to", "lab", "launch_status", "lead_status", "localization_language", "localization_market_team", "localization_status", "meeting_minutes", "meeting_needed", "minutes", "mrr", "must_localize", "name_of_foundation", "need_to_follow_up", "next_appointment", "next_steps_sales", "num_people", "number_of_user_reports", "office_location", "onboarding_activity", "owner", "participants_needed", "patient_date_of_birth", "patient_email", "patient_phone", "patient_status", "phone_number", "planning_category", "point_of_contact", "position", "post_format", "prescription", "priority", "priority_level", "product", "product_stage", "progress", "project_size", "project_status", "proposed_budget", "publish_status", "reason_for_scan", "referral", "request_type", "research_status", "responsible_department", "responsible_team", "risk_assessment_status", "room_name", "sales_counterpart", "sentiment", "shipping_link", "social_channels", "stage", "status", "status_design", "status_of_initiative", "system_setup", "task_progress", "team", "team_marketing", "team_responsible", "time_it_takes_to_complete_tasks", "timeframe", "treatment_type", "type_work_requests_it", "use_agency", "user_name", "vendor_category", "vendor_type", "word_count", null ], "example": "priority" } } } ] }, { "type": "object", "properties": { "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id", "reference" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "is_value_read_only": { "description": "*Conditional*. This flag describes whether a custom field is read only.", "type": "boolean", "example": false }, "created_by": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "nullable": true } ] }, "people_value": { "description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field.", "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "reference_value": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.", "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "privacy_setting": { "description": "The privacy setting of the custom field. *Note: Administrators in your organization may restrict the values of `privacy_setting`.*", "type": "string", "enum": [ "public_with_guests", "public", "private" ], "example": "public_with_guests" }, "default_access_level": { "description": "The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself.", "type": "string", "enum": [ "admin", "editor", "user" ], "example": "user" }, "resource_subtype": { "description": "The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "example": "text", "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "reference" ] } } } ] }, "readOnly": true }, "custom_type": { "allOf": [ { "description": "Custom Types extend the types of Asana Objects, currently only Custom Tasks are supported.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type.", "example": "Bug ticket" } } }, { "nullable": true } ] }, "custom_type_status_option": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_type_status_option", "x-insert-after": "gid" }, "name": { "type": "string", "description": "The name of the custom type status option.", "example": "Solution pending" } } }, { "nullable": true } ] }, "followers": { "description": "Array of users following this task.", "type": "array", "readOnly": true, "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "parent": { "allOf": [ { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, { "type": "object", "readOnly": true, "description": "The parent of this task, or `null` if this is not a subtask. This property cannot be modified using a PUT request but you can change it with the `setParent` endpoint. You can create subtasks by using the subtasks endpoint.", "nullable": true } ] }, "projects": { "description": "*Create-only.* Array of projects this task is associated with. At task creation time, this array can be used to add the task to many projects at once. After task creation, these associations can be modified using the addProject and removeProject endpoints.", "type": "array", "readOnly": true, "items": { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } } }, "tags": { "description": "Array of tags associated with this task. In order to change tags on an existing task use `addTag` and `removeTag`.", "type": "array", "readOnly": true, "items": { "description": "A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "tag", "x-insert-after": "gid" }, "name": { "description": "Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, "example": [ { "gid": "59746", "name": "Grade A" } ] }, "workspace": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "readOnly": true, "description": "*Create-only*. The workspace this task is associated with. Once created, task cannot be moved to a different workspace. This attribute can only be specified at creation time." } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/1/12345/task/123456789" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet custom_id = \"EX-1\"; // String | Generated custom ID for a task.\n\ntasksApiInstance.getTaskForCustomID(workspace_gid, custom_id).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.getTaskForCustomID(workspaceGid, customId, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/tasks/search": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "text", "in": "query", "description": "Performs full-text search on both task name and description", "schema": { "type": "string" }, "example": "Bug" }, { "name": "resource_subtype", "in": "query", "description": "Filters results by the task's resource_subtype", "schema": { "type": "string", "enum": [ "default_task", "milestone", "approval" ], "default": "milestone" } }, { "name": "assignee.any", "in": "query", "description": "Comma-separated list of user identifiers", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "assignee.not", "in": "query", "description": "Comma-separated list of user identifiers", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "portfolios.any", "in": "query", "description": "Comma-separated list of portfolio IDs", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "projects.any", "in": "query", "description": "Comma-separated list of project IDs", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "projects.not", "in": "query", "description": "Comma-separated list of project IDs", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "projects.all", "in": "query", "description": "Comma-separated list of project IDs", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "sections.any", "in": "query", "description": "Comma-separated list of section or column IDs", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "sections.not", "in": "query", "description": "Comma-separated list of section or column IDs", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "sections.all", "in": "query", "description": "Comma-separated list of section or column IDs", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "tags.any", "in": "query", "description": "Comma-separated list of tag IDs", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "tags.not", "in": "query", "description": "Comma-separated list of tag IDs", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "tags.all", "in": "query", "description": "Comma-separated list of tag IDs", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "teams.any", "in": "query", "description": "Comma-separated list of team IDs", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "followers.any", "in": "query", "description": "Comma-separated list of user identifiers", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "followers.not", "in": "query", "description": "Comma-separated list of user identifiers", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "created_by.any", "in": "query", "description": "Comma-separated list of user identifiers", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "created_by.not", "in": "query", "description": "Comma-separated list of user identifiers", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "assigned_by.any", "in": "query", "description": "Comma-separated list of user identifiers", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "assigned_by.not", "in": "query", "description": "Comma-separated list of user identifiers", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "liked_by.not", "in": "query", "description": "Comma-separated list of user identifiers", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "commented_on_by.not", "in": "query", "description": "Comma-separated list of user identifiers", "schema": { "type": "string" }, "example": "12345,23456,34567" }, { "name": "due_on.before", "in": "query", "description": "ISO 8601 date string", "schema": { "type": "string", "format": "date" }, "example": "2019-09-15" }, { "name": "due_on.after", "in": "query", "description": "ISO 8601 date string", "schema": { "type": "string", "format": "date" }, "example": "2019-09-15" }, { "name": "due_on", "in": "query", "description": "ISO 8601 date string or `null`", "schema": { "type": "string", "format": "date", "nullable": true }, "example": "2019-09-15" }, { "name": "due_at.before", "in": "query", "description": "ISO 8601 datetime string", "schema": { "type": "string", "format": "date-time" }, "example": "2019-04-15T01:01:46.055Z" }, { "name": "due_at.after", "in": "query", "description": "ISO 8601 datetime string", "schema": { "type": "string", "format": "date-time" }, "example": "2019-04-15T01:01:46.055Z" }, { "name": "start_on.before", "in": "query", "description": "ISO 8601 date string", "schema": { "type": "string", "format": "date" }, "example": "2019-09-15" }, { "name": "start_on.after", "in": "query", "description": "ISO 8601 date string", "schema": { "type": "string", "format": "date" }, "example": "2019-09-15" }, { "name": "start_on", "in": "query", "description": "ISO 8601 date string or `null`", "schema": { "type": "string", "format": "date", "nullable": true }, "example": "2019-09-15" }, { "name": "created_on.before", "in": "query", "description": "ISO 8601 date string", "schema": { "type": "string", "format": "date" }, "example": "2019-09-15" }, { "name": "created_on.after", "in": "query", "description": "ISO 8601 date string", "schema": { "type": "string", "format": "date" }, "example": "2019-09-15" }, { "name": "created_on", "in": "query", "description": "ISO 8601 date string or `null`", "schema": { "type": "string", "format": "date", "nullable": true }, "example": "2019-09-15" }, { "name": "created_at.before", "in": "query", "description": "ISO 8601 datetime string", "schema": { "type": "string", "format": "date-time" }, "example": "2019-04-15T01:01:46.055Z" }, { "name": "created_at.after", "in": "query", "description": "ISO 8601 datetime string", "schema": { "type": "string", "format": "date-time" }, "example": "2019-04-15T01:01:46.055Z" }, { "name": "completed_on.before", "in": "query", "description": "ISO 8601 date string", "schema": { "type": "string", "format": "date" }, "example": "2019-09-15" }, { "name": "completed_on.after", "in": "query", "description": "ISO 8601 date string", "schema": { "type": "string", "format": "date" }, "example": "2019-09-15" }, { "name": "completed_on", "in": "query", "description": "ISO 8601 date string or `null`", "schema": { "type": "string", "format": "date", "nullable": true }, "example": "2019-09-15" }, { "name": "completed_at.before", "in": "query", "description": "ISO 8601 datetime string", "schema": { "type": "string", "format": "date-time" }, "example": "2019-04-15T01:01:46.055Z" }, { "name": "completed_at.after", "in": "query", "description": "ISO 8601 datetime string", "schema": { "type": "string", "format": "date-time" }, "example": "2019-04-15T01:01:46.055Z" }, { "name": "modified_on.before", "in": "query", "description": "ISO 8601 date string", "schema": { "type": "string", "format": "date" }, "example": "2019-09-15" }, { "name": "modified_on.after", "in": "query", "description": "ISO 8601 date string", "schema": { "type": "string", "format": "date" }, "example": "2019-09-15" }, { "name": "modified_on", "in": "query", "description": "ISO 8601 date string or `null`", "schema": { "type": "string", "format": "date", "nullable": true }, "example": "2019-09-15" }, { "name": "modified_at.before", "in": "query", "description": "ISO 8601 datetime string", "schema": { "type": "string", "format": "date-time" }, "example": "2019-04-15T01:01:46.055Z" }, { "name": "modified_at.after", "in": "query", "description": "ISO 8601 datetime string", "schema": { "type": "string", "format": "date-time" }, "example": "2019-04-15T01:01:46.055Z" }, { "name": "is_blocking", "in": "query", "description": "Filter to incomplete tasks with dependents", "schema": { "type": "boolean" }, "example": false }, { "name": "is_blocked", "in": "query", "description": "Filter to tasks with incomplete dependencies", "schema": { "type": "boolean" }, "example": false }, { "name": "has_attachment", "in": "query", "description": "Filter to tasks with attachments", "schema": { "type": "boolean" }, "example": false }, { "name": "completed", "in": "query", "description": "Filter to completed tasks", "schema": { "type": "boolean" }, "example": false }, { "name": "is_subtask", "in": "query", "description": "Filter to subtasks", "schema": { "type": "boolean" }, "example": false }, { "name": "sort_by", "in": "query", "description": "One of `due_date`, `created_at`, `completed_at`, `likes`, or `modified_at`, defaults to `modified_at`", "schema": { "type": "string", "enum": [ "due_date", "created_at", "completed_at", "likes", "modified_at" ], "default": "modified_at" }, "example": "likes" }, { "name": "sort_ascending", "in": "query", "description": "Default `false`", "schema": { "type": "boolean", "default": false }, "example": true } ], "get": { "summary": "Search tasks in a workspace", "description": "Required scope: tasks:read\n\nTo mirror the functionality of the Asana web app's advanced search feature, the Asana API has a task search endpoint that allows you to build complex filters to find and retrieve the exact data you need.\n#### Premium access\nLike the Asana web product's advance search feature, this search endpoint will only be available to premium Asana users. A user is premium if any of the following is true:\n\n- The workspace in which the search is being performed is a premium workspace - The user is a member of a premium team inside the workspace\n\nEven if a user is only a member of a premium team inside a non-premium workspace, search will allow them to find data anywhere in the workspace, not just inside the premium team. Making a search request using credentials of a non-premium user will result in a `402 Payment Required` error.\n#### Pagination\nSearch results are not stable; repeating the same query multiple times may return the data in a different order, even if the data do not change. Because of this, the traditional [pagination](https://developers.asana.com/docs/#pagination) available elsewhere in the Asana API is not available here. However, you can paginate manually by sorting the search results by their creation time and then modifying each subsequent query to exclude data you have already seen. Page sizes are limited to a maximum of 100 items, and can be specified by the `limit` query parameter.\n#### Eventual consistency\nChanges in Asana (regardless of whether they\u2019re made though the web product or the API) are forwarded to our search infrastructure to be indexed. This process can take between 10 and 60 seconds to complete under normal operation, and longer during some production incidents. Making a change to a task that would alter its presence in a particular search query will not be reflected immediately. This is also true of the advanced search feature in the web product.\n#### Rate limits\nYou may receive a `429 Too Many Requests` response if you hit any of our [rate limits](https://developers.asana.com/docs/#rate-limits).\n#### Custom field parameters\n| Parameter name | Custom field type | Accepted type |\n|---|---|---|\n| custom_fields.{gid}.is_set | All | Boolean |\n| custom_fields.{gid}.value | Text | String |\n| custom_fields.{gid}.value | Number | Number |\n| custom_fields.{gid}.value | Enum | Enum option ID |\n| custom_fields.{gid}.starts_with | Text only | String |\n| custom_fields.{gid}.ends_with | Text only | String |\n| custom_fields.{gid}.contains | Text only | String |\n| custom_fields.{gid}.less_than | Number only | Number |\n| custom_fields.{gid}.greater_than | Number only | Number |\n\n\nFor example, if the gid of the custom field is 12345, these query parameter to find tasks where it is set would be `custom_fields.12345.is_set=true`. To match an exact value for an enum custom field, use the gid of the desired enum option and not the name of the enum option: `custom_fields.12345.value=67890`.\n\n**Not Supported**: searching for multiple exact matches of a custom field, searching for multi-enum custom field\n\n*Note: If you specify `projects.any` and `sections.any`, you will receive tasks for the project **and** tasks for the section. If you're looking for only tasks in a section, omit the `projects.any` from the request.*", "tags": [ "Tasks" ], "operationId": "searchTasksForWorkspace", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "actual_time_minutes", "approval_status", "assignee", "assignee.name", "assignee_section", "assignee_section.name", "assignee_status", "completed", "completed_at", "completed_by", "completed_by.name", "created_at", "created_by", "custom_fields", "custom_fields.asana_created_field", "custom_fields.created_by", "custom_fields.created_by.name", "custom_fields.currency_code", "custom_fields.custom_label", "custom_fields.custom_label_position", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.default_access_level", "custom_fields.description", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.format", "custom_fields.has_notifications_enabled", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.is_global_to_workspace", "custom_fields.is_value_read_only", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.people_value", "custom_fields.people_value.name", "custom_fields.precision", "custom_fields.privacy_setting", "custom_fields.reference_value", "custom_fields.reference_value.name", "custom_fields.representation_type", "custom_fields.resource_subtype", "custom_fields.text_value", "custom_fields.type", "custom_type", "custom_type.name", "custom_type_status_option", "custom_type_status_option.name", "dependencies", "dependents", "due_at", "due_on", "external", "external.data", "followers", "followers.name", "hearted", "hearts", "hearts.user", "hearts.user.name", "html_notes", "is_rendered_as_separator", "liked", "likes", "likes.user", "likes.user.name", "memberships", "memberships.project", "memberships.project.name", "memberships.section", "memberships.section.name", "modified_at", "name", "notes", "num_hearts", "num_likes", "num_subtasks", "parent", "parent.created_by", "parent.name", "parent.resource_subtype", "permalink_url", "projects", "projects.name", "resource_subtype", "start_at", "start_on", "tags", "tags.name", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the section's tasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.tasks.searchTasksForWorkspace(workspaceGid, sortAscending, sortBy, isSubtask, completed, hasAttachment, isBlocked, isBlocking, modifiedAtAfter, modifiedAtBefore, dueOn, modifiedOn, modifiedOnAfter, modifiedOnBefore, completedAtAfter, completedAtBefore, completedOn, completedOnAfter, completedOnBefore, createdAtAfter, dueOnAfter, createdAtBefore, createdOn, createdOnAfter, createdOnBefore, startOn, startOnAfter, startOnBefore, dueAtAfter, dueAtBefore, dueOnBefore, commentedOnByNot, likedByNot, assignedByNot, assignedByAny, createdByNot, createdByAny, followersNot, teamsAny, tagsAll, tagsNot, tagsAny, sectionsAll, sectionsNot, sectionsAny, projectsAll, projectsNot, projectsAny, portfoliosAny, assigneeNot, assigneeAny, resourceSubtype, text)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet tasksApiInstance = new Asana.TasksApi();\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'text': \"Bug\", \n 'resource_subtype': \"milestone\", \n 'assignee.any': \"12345,23456,34567\", \n 'assignee.not': \"12345,23456,34567\", \n 'portfolios.any': \"12345,23456,34567\", \n 'projects.any': \"12345,23456,34567\", \n 'projects.not': \"12345,23456,34567\", \n 'projects.all': \"12345,23456,34567\", \n 'sections.any': \"12345,23456,34567\", \n 'sections.not': \"12345,23456,34567\", \n 'sections.all': \"12345,23456,34567\", \n 'tags.any': \"12345,23456,34567\", \n 'tags.not': \"12345,23456,34567\", \n 'tags.all': \"12345,23456,34567\", \n 'teams.any': \"12345,23456,34567\", \n 'followers.any': \"12345,23456,34567\", \n 'followers.not': \"12345,23456,34567\", \n 'created_by.any': \"12345,23456,34567\", \n 'created_by.not': \"12345,23456,34567\", \n 'assigned_by.any': \"12345,23456,34567\", \n 'assigned_by.not': \"12345,23456,34567\", \n 'liked_by.not': \"12345,23456,34567\", \n 'commented_on_by.not': \"12345,23456,34567\", \n 'due_on.before': \"2019-09-15\", \n 'due_on.after': \"2019-09-15\", \n 'due_on': \"2019-09-15\", \n 'due_at.before': \"2019-04-15T01:01:46.055Z\", \n 'due_at.after': \"2019-04-15T01:01:46.055Z\", \n 'start_on.before': \"2019-09-15\", \n 'start_on.after': \"2019-09-15\", \n 'start_on': \"2019-09-15\", \n 'created_on.before': \"2019-09-15\", \n 'created_on.after': \"2019-09-15\", \n 'created_on': \"2019-09-15\", \n 'created_at.before': \"2019-04-15T01:01:46.055Z\", \n 'created_at.after': \"2019-04-15T01:01:46.055Z\", \n 'completed_on.before': \"2019-09-15\", \n 'completed_on.after': \"2019-09-15\", \n 'completed_on': \"2019-09-15\", \n 'completed_at.before': \"2019-04-15T01:01:46.055Z\", \n 'completed_at.after': \"2019-04-15T01:01:46.055Z\", \n 'modified_on.before': \"2019-09-15\", \n 'modified_on.after': \"2019-09-15\", \n 'modified_on': \"2019-09-15\", \n 'modified_at.before': \"2019-04-15T01:01:46.055Z\", \n 'modified_at.after': \"2019-04-15T01:01:46.055Z\", \n 'is_blocking': false, \n 'is_blocked': false, \n 'has_attachment': false, \n 'completed': false, \n 'is_subtask': false, \n 'sort_by': \"modified_at\", \n 'sort_ascending': false, \n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\"\n};\n// Custom fields query\nopts['custom_fields.123.is_set'] = true; // Boolean | Replace \"123\" with . NOTE: searching for multiple exact matches of a custom field, searching for multi-enum custom field\nopts['custom_fields.123.value'] = '456'; // String, Number, Enum option ID | Replace \"123\" with . NOTE: searching for multiple exact matches of a custom field, searching for multi-enum custom field\nopts['custom_fields.123.starts_with'] = 'start'; // String | Replace \"123\" with . NOTE: searching for multiple exact matches of a custom field, searching for multi-enum custom field\nopts['custom_fields.123.ends_with'] = 'end'; // String | Replace \"123\" with . NOTE: searching for multiple exact matches of a custom field, searching for multi-enum custom field\nopts['custom_fields.123.contains'] = 'first'; // String | Replace \"123\" with . NOTE: searching for multiple exact matches of a custom field, searching for multi-enum custom field\nopts['custom_fields.123.less_than'] = 10; // Number | Replace \"123\" with . NOTE: searching for multiple exact matches of a custom field, searching for multi-enum custom field\nopts['custom_fields.123.greater_than'] = 100; // Number | Replace \"123\" with . NOTE: searching for multiple exact matches of a custom field, searching for multi-enum custom field\ntasksApiInstance.searchTasksForWorkspace(workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.tasks.searchTasksForWorkspace(workspaceGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntasks_api_instance = asana.TasksApi(api_client)\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'text': \"Bug\", # str | Performs full-text search on both task name and description\n 'resource_subtype': \"milestone\", # str | Filters results by the task's resource_subtype\n 'assignee.any': \"12345,23456,34567\", # str | Comma-separated list of user identifiers\n 'assignee.not': \"12345,23456,34567\", # str | Comma-separated list of user identifiers\n 'portfolios.any': \"12345,23456,34567\", # str | Comma-separated list of portfolio IDs\n 'projects.any': \"12345,23456,34567\", # str | Comma-separated list of project IDs\n 'projects.not': \"12345,23456,34567\", # str | Comma-separated list of project IDs\n 'projects.all': \"12345,23456,34567\", # str | Comma-separated list of project IDs\n 'sections.any': \"12345,23456,34567\", # str | Comma-separated list of section or column IDs\n 'sections.not': \"12345,23456,34567\", # str | Comma-separated list of section or column IDs\n 'sections.all': \"12345,23456,34567\", # str | Comma-separated list of section or column IDs\n 'tags.any': \"12345,23456,34567\", # str | Comma-separated list of tag IDs\n 'tags.not': \"12345,23456,34567\", # str | Comma-separated list of tag IDs\n 'tags.all': \"12345,23456,34567\", # str | Comma-separated list of tag IDs\n 'teams.any': \"12345,23456,34567\", # str | Comma-separated list of team IDs\n 'followers.any': \"12345,23456,34567\", # str | Comma-separated list of user identifiers\n 'followers.not': \"12345,23456,34567\", # str | Comma-separated list of user identifiers\n 'created_by.any': \"12345,23456,34567\", # str | Comma-separated list of user identifiers\n 'created_by.not': \"12345,23456,34567\", # str | Comma-separated list of user identifiers\n 'assigned_by.any': \"12345,23456,34567\", # str | Comma-separated list of user identifiers\n 'assigned_by.not': \"12345,23456,34567\", # str | Comma-separated list of user identifiers\n 'liked_by.not': \"12345,23456,34567\", # str | Comma-separated list of user identifiers\n 'commented_on_by.not': \"12345,23456,34567\", # str | Comma-separated list of user identifiers\n 'due_on.before': '2019-09-15', # date | ISO 8601 date string\n 'due_on.after': '2019-09-15', # date | ISO 8601 date string\n 'due_on': '2019-09-15', # date | ISO 8601 date string or `null`\n 'due_at.before': '2019-04-15T01:01:46.055Z', # datetime | ISO 8601 datetime string\n 'due_at.after': '2019-04-15T01:01:46.055Z', # datetime | ISO 8601 datetime string\n 'start_on.before': '2019-09-15', # date | ISO 8601 date string\n 'start_on.after': '2019-09-15', # date | ISO 8601 date string\n 'start_on': '2019-09-15', # date | ISO 8601 date string or `null`\n 'created_on.before': '2019-09-15', # date | ISO 8601 date string\n 'created_on.after': '2019-09-15', # date | ISO 8601 date string\n 'created_on': '2019-09-15', # date | ISO 8601 date string or `null`\n 'created_at.before': '2019-04-15T01:01:46.055Z', # datetime | ISO 8601 datetime string\n 'created_at.after': '2019-04-15T01:01:46.055Z', # datetime | ISO 8601 datetime string\n 'completed_on.before': '2019-09-15', # date | ISO 8601 date string\n 'completed_on.after': '2019-09-15', # date | ISO 8601 date string\n 'completed_on': '2019-09-15', # date | ISO 8601 date string or `null`\n 'completed_at.before': '2019-04-15T01:01:46.055Z', # datetime | ISO 8601 datetime string\n 'completed_at.after': '2019-04-15T01:01:46.055Z', # datetime | ISO 8601 datetime string\n 'modified_on.before': '2019-09-15', # date | ISO 8601 date string\n 'modified_on.after': '2019-09-15', # date | ISO 8601 date string\n 'modified_on': '2019-09-15', # date | ISO 8601 date string or `null`\n 'modified_at.before': '2019-04-15T01:01:46.055Z', # datetime | ISO 8601 datetime string\n 'modified_at.after': '2019-04-15T01:01:46.055Z', # datetime | ISO 8601 datetime string\n 'is_blocking': False, # bool | Filter to incomplete tasks with dependents\n 'is_blocked': False, # bool | Filter to tasks with incomplete dependencies\n 'has_attachment': False, # bool | Filter to tasks with attachments\n 'completed': False, # bool | Filter to completed tasks\n 'is_subtask': False, # bool | Filter to subtasks\n 'sort_by': \"modified_at\", # str | One of `due_date`, `created_at`, `completed_at`, `likes`, or `modified_at`, defaults to `modified_at`\n 'sort_ascending': True, # bool | Default `false`\n 'opt_fields': \"actual_time_minutes,approval_status,assignee,assignee.name,assignee_section,assignee_section.name,assignee_status,completed,completed_at,completed_by,completed_by.name,created_at,created_by,custom_fields,custom_fields.asana_created_field,custom_fields.created_by,custom_fields.created_by.name,custom_fields.currency_code,custom_fields.custom_label,custom_fields.custom_label_position,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.default_access_level,custom_fields.description,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.format,custom_fields.has_notifications_enabled,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.is_global_to_workspace,custom_fields.is_value_read_only,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.people_value,custom_fields.people_value.name,custom_fields.precision,custom_fields.privacy_setting,custom_fields.reference_value,custom_fields.reference_value.name,custom_fields.representation_type,custom_fields.resource_subtype,custom_fields.text_value,custom_fields.type,custom_type,custom_type.name,custom_type_status_option,custom_type_status_option.name,dependencies,dependents,due_at,due_on,external,external.data,followers,followers.name,hearted,hearts,hearts.user,hearts.user.name,html_notes,is_rendered_as_separator,liked,likes,likes.user,likes.user.name,memberships,memberships.project,memberships.project.name,memberships.section,memberships.section.name,modified_at,name,notes,num_hearts,num_likes,num_subtasks,parent,parent.created_by,parent.name,parent.resource_subtype,permalink_url,projects,projects.name,resource_subtype,start_at,start_on,tags,tags.name,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\nopts['custom_fields.123.is_set'] = True # bool | Filiter to tasks with custom field set or unset. Note: searching for multiple exact matches of a custom field, searching for multi-enum custom field\nopts['custom_fields.123.value'] = '456' # str or bool or Enum option ID | Filter to tasks with custom field that matches the provided value. Note: searching for multiple exact matches of a custom field, searching for multi-enum custom field\nopts['custom_fields.123.starts_with'] = 'start' # string | Filter to tasks with custom field that starts with provided string. Note: searching for multiple exact matches of a custom field, searching for multi-enum custom field\nopts['custom_fields.123.ends_with'] = 'end' # string | Filter to tasks with custom field that ends in provided string. Note: searching for multiple exact matches of a custom field, searching for multi-enum custom field\nopts['custom_fields.123.contains'] = 'first' # string | Filter to tasks with custom field that contains the provided string. Note: searching for multiple exact matches of a custom field, searching for multi-enum custom field\nopts['custom_fields.123.less_than'] = 10 # number | Filter to tasks with custom field with number value less than the provided number. Note: searching for multiple exact matches of a custom field, searching for multi-enum custom field\nopts['custom_fields.123.greater_than'] = 100 # number | Filter to tasks with custom field with number value greater than the provided number. Note: searching for multiple exact matches of a custom field, searching for multi-enum custom field\n\ntry:\n # Search tasks in a workspace\n api_response = tasks_api_instance.search_tasks_for_workspace(workspace_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TasksApi->search_tasks_for_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.tasks.search_tasks_for_workspace(workspace_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "tasks->searchTasksForWorkspace($workspace_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.tasks.search_tasks_for_workspace(workspace_gid: 'workspace_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/team_memberships/{team_membership_gid}": { "parameters": [ { "name": "team_membership_gid", "in": "path", "required": true, "schema": { "type": "string" }, "example": "724362", "x-env-variable": "team_membership" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a team membership", "description": "Required scope: team_memberships:read\n\n\n \n \n \n \n \n \n \n \n
FieldRequired Scope
teamteams:read
\n\nReturns the complete team membership record for a single team membership.", "tags": [ "Team memberships" ], "operationId": "getTeamMembership", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "is_admin", "is_guest", "is_limited_access", "team", "team.name", "user", "user.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "is_admin", "is_guest", "is_limited_access", "team", "team.name", "user", "user.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested team membership.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "This object represents a user's connection to a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team_membership", "x-insert-after": "gid" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "team": { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, "is_guest": { "type": "boolean", "description": "Describes if the user is a guest in the team.", "example": false }, "is_limited_access": { "type": "boolean", "readOnly": true, "description": "Describes if the user has limited access to the team.", "example": false }, "is_admin": { "type": "boolean", "description": "Describes if the user is a team admin.", "example": false } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "team_memberships:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.teammemberships.getTeamMembership(teamMembershipGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet teamMembershipsApiInstance = new Asana.TeamMembershipsApi();\nlet team_membership_gid = \"724362\"; // String | \nlet opts = { \n 'opt_fields': \"is_admin,is_guest,is_limited_access,team,team.name,user,user.name\"\n};\nteamMembershipsApiInstance.getTeamMembership(team_membership_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.teammemberships.getTeamMembership(teamMembershipGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nteam_memberships_api_instance = asana.TeamMembershipsApi(api_client)\nteam_membership_gid = \"724362\" # str | \nopts = {\n 'opt_fields': \"is_admin,is_guest,is_limited_access,team,team.name,user,user.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a team membership\n api_response = team_memberships_api_instance.get_team_membership(team_membership_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TeamMembershipsApi->get_team_membership: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.team_memberships.get_team_membership(team_membership_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "teammemberships->getTeamMembership($team_membership_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.team_memberships.get_team_membership(team_membership_gid: 'team_membership_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/team_memberships": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get team memberships", "description": "Required scope: team_memberships:read\n\nReturns compact team membership records.", "tags": [ "Team memberships" ], "operationId": "getTeamMemberships", "parameters": [ { "name": "team", "in": "query", "description": "Globally unique identifier for the team.", "schema": { "type": "string" }, "example": "159874" }, { "name": "user", "in": "query", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user. This parameter must be used with the workspace parameter.", "schema": { "type": "string" }, "example": "512241" }, { "name": "workspace", "in": "query", "description": "Globally unique identifier for the workspace. This parameter must be used with the user parameter.", "schema": { "type": "string" }, "example": "31326" }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "is_admin", "is_guest", "is_limited_access", "offset", "path", "team", "team.name", "uri", "user", "user.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "is_admin", "is_guest", "is_limited_access", "offset", "path", "team", "team.name", "uri", "user", "user.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested team memberships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "This object represents a user's connection to a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team_membership", "x-insert-after": "gid" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "team": { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, "is_guest": { "type": "boolean", "description": "Describes if the user is a guest in the team.", "example": false }, "is_limited_access": { "type": "boolean", "readOnly": true, "description": "Describes if the user has limited access to the team.", "example": false }, "is_admin": { "type": "boolean", "description": "Describes if the user is a team admin.", "example": false } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "team_memberships:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.teammemberships.getTeamMemberships(workspace, user, team)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet teamMembershipsApiInstance = new Asana.TeamMembershipsApi();\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'team': \"159874\", \n 'user': \"512241\", \n 'workspace': \"31326\", \n 'opt_fields': \"is_admin,is_guest,is_limited_access,offset,path,team,team.name,uri,user,user.name\"\n};\nteamMembershipsApiInstance.getTeamMemberships(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.teammemberships.getTeamMemberships({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nteam_memberships_api_instance = asana.TeamMembershipsApi(api_client)\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'team': \"159874\", # str | Globally unique identifier for the team.\n 'user': \"512241\", # str | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user. This parameter must be used with the workspace parameter.\n 'workspace': \"31326\", # str | Globally unique identifier for the workspace. This parameter must be used with the user parameter.\n 'opt_fields': \"is_admin,is_guest,is_limited_access,offset,path,team,team.name,uri,user,user.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get team memberships\n api_response = team_memberships_api_instance.get_team_memberships(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TeamMembershipsApi->get_team_memberships: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.team_memberships.get_team_memberships({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "teammemberships->getTeamMemberships(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.team_memberships.get_team_memberships(param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/teams/{team_gid}/team_memberships": { "parameters": [ { "name": "team_gid", "in": "path", "description": "Globally unique identifier for the team.", "required": true, "schema": { "type": "string" }, "example": "159874", "x-env-variable": "team" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get memberships from a team", "description": "Required scope: team_memberships:read\n\nReturns the compact team memberships for the team.", "tags": [ "Team memberships" ], "operationId": "getTeamMembershipsForTeam", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "is_admin", "is_guest", "is_limited_access", "offset", "path", "team", "team.name", "uri", "user", "user.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "is_admin", "is_guest", "is_limited_access", "offset", "path", "team", "team.name", "uri", "user", "user.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested team's memberships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "This object represents a user's connection to a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team_membership", "x-insert-after": "gid" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "team": { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, "is_guest": { "type": "boolean", "description": "Describes if the user is a guest in the team.", "example": false }, "is_limited_access": { "type": "boolean", "readOnly": true, "description": "Describes if the user has limited access to the team.", "example": false }, "is_admin": { "type": "boolean", "description": "Describes if the user is a team admin.", "example": false } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "team_memberships:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.teammemberships.getTeamMembershipsForTeam(teamGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet teamMembershipsApiInstance = new Asana.TeamMembershipsApi();\nlet team_gid = \"159874\"; // String | Globally unique identifier for the team.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"is_admin,is_guest,is_limited_access,offset,path,team,team.name,uri,user,user.name\"\n};\nteamMembershipsApiInstance.getTeamMembershipsForTeam(team_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.teammemberships.getTeamMembershipsForTeam(teamGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nteam_memberships_api_instance = asana.TeamMembershipsApi(api_client)\nteam_gid = \"159874\" # str | Globally unique identifier for the team.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"is_admin,is_guest,is_limited_access,offset,path,team,team.name,uri,user,user.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get memberships from a team\n api_response = team_memberships_api_instance.get_team_memberships_for_team(team_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TeamMembershipsApi->get_team_memberships_for_team: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.team_memberships.get_team_memberships_for_team(team_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "teammemberships->getTeamMembershipsForTeam($team_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.team_memberships.get_team_memberships_for_team(team_gid: 'team_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/users/{user_gid}/team_memberships": { "parameters": [ { "name": "user_gid", "in": "path", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "required": true, "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get memberships from a user", "description": "Required scope: team_memberships:read\n\nReturns the compact team membership records for the user.", "tags": [ "Team memberships" ], "operationId": "getTeamMembershipsForUser", "parameters": [ { "name": "workspace", "description": "Globally unique identifier for the workspace.", "in": "query", "schema": { "type": "string" }, "example": "31326", "required": true }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "is_admin", "is_guest", "is_limited_access", "offset", "path", "team", "team.name", "uri", "user", "user.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "is_admin", "is_guest", "is_limited_access", "offset", "path", "team", "team.name", "uri", "user", "user.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested users's memberships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "This object represents a user's connection to a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team_membership", "x-insert-after": "gid" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "team": { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, "is_guest": { "type": "boolean", "description": "Describes if the user is a guest in the team.", "example": false }, "is_limited_access": { "type": "boolean", "readOnly": true, "description": "Describes if the user has limited access to the team.", "example": false }, "is_admin": { "type": "boolean", "description": "Describes if the user is a team admin.", "example": false } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "team_memberships:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.teammemberships.getTeamMembershipsForUser(userGid, workspace)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet teamMembershipsApiInstance = new Asana.TeamMembershipsApi();\nlet user_gid = \"me\"; // String | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\nlet workspace = \"31326\"; // String | Globally unique identifier for the workspace.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"is_admin,is_guest,is_limited_access,offset,path,team,team.name,uri,user,user.name\"\n};\nteamMembershipsApiInstance.getTeamMembershipsForUser(user_gid, workspace, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.teammemberships.getTeamMembershipsForUser(userGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nteam_memberships_api_instance = asana.TeamMembershipsApi(api_client)\nuser_gid = \"me\" # str | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\nworkspace = \"31326\" # str | Globally unique identifier for the workspace.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"is_admin,is_guest,is_limited_access,offset,path,team,team.name,uri,user,user.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get memberships from a user\n api_response = team_memberships_api_instance.get_team_memberships_for_user(user_gid, workspace, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TeamMembershipsApi->get_team_memberships_for_user: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.team_memberships.get_team_memberships_for_user(user_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "teammemberships->getTeamMembershipsForUser($user_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.team_memberships.get_team_memberships_for_user(user_gid: 'user_gid', workspace: ''workspace_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/teams": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Create a team", "description": "Creates a team within the current workspace.", "tags": [ "Teams" ], "operationId": "createTeam", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "description", "edit_team_name_or_description_access_level", "edit_team_visibility_or_trash_team_access_level", "endorsed", "guest_invite_management_access_level", "html_description", "join_request_management_access_level", "member_invite_management_access_level", "name", "organization", "organization.name", "permalink_url", "team_content_management_access_level", "team_member_removal_access_level", "visibility" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "description", "edit_team_name_or_description_access_level", "edit_team_visibility_or_trash_team_access_level", "endorsed", "guest_invite_management_access_level", "html_description", "join_request_management_access_level", "member_invite_management_access_level", "name", "organization", "organization.name", "permalink_url", "team_content_management_access_level", "team_member_removal_access_level", "visibility" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The team to create.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "properties": { "description": { "description": "The description of the team.\n", "type": "string", "example": "All developers should be members of this team." }, "html_description": { "description": "The description of the team with formatting as HTML.\n", "type": "string", "example": "All developers should be members of this team." }, "organization": { "type": "string", "description": "The organization/workspace the team belongs to. This must be the same organization you are in and cannot be changed once set.\n", "example": "123456789" }, "visibility": { "description": "The visibility of the team to users in the same organization\n", "type": "string", "enum": [ "secret", "request_to_join", "public" ] }, "edit_team_name_or_description_access_level": { "description": "Controls who can edit team name and description\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "edit_team_visibility_or_trash_team_access_level": { "description": "Controls who can edit team visibility and trash teams\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "member_invite_management_access_level": { "description": "Controls who can accept or deny member invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "guest_invite_management_access_level": { "description": "Controls who can accept or deny guest invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "join_request_management_access_level": { "description": "Controls who can accept or deny join team requests for a Membership by Request team. This field can only be updated when the team's `visibility` field is `request_to_join`.\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_member_removal_access_level": { "description": "Controls who can remove team members\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_content_management_access_level": { "description": "Controls who can create and share content with the team\n", "type": "string", "enum": [ "no_restriction", "only_team_admins" ] }, "endorsed": { "description": "Whether the team has been endorsed\n", "type": "boolean", "example": false } } } ] } } } } } }, "responses": { "201": { "description": "Successfully created a new team.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the team.\n", "type": "string", "example": "All developers should be members of this team." }, "html_description": { "description": "[Opt In](/docs/inputoutput-options). The description of the team with formatting as HTML.\n", "type": "string", "example": "All developers should be members of this team." }, "organization": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "description": "The organization/workspace the team belongs to.\n" } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" }, "visibility": { "description": "The visibility of the team to users in the same organization\n", "type": "string", "enum": [ "secret", "request_to_join", "public" ] }, "edit_team_name_or_description_access_level": { "description": "Controls who can edit team name and description\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "edit_team_visibility_or_trash_team_access_level": { "description": "Controls who can edit team visibility and trash teams\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "member_invite_management_access_level": { "description": "Controls who can accept or deny member invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "guest_invite_management_access_level": { "description": "Controls who can accept or deny guest invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "join_request_management_access_level": { "description": "Controls who can accept or deny join team requests for a Membership by Request team. This field can only be updated when the team's `visibility` field is `request_to_join`.\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_member_removal_access_level": { "description": "Controls who can remove team members\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_content_management_access_level": { "description": "Controls who can create and share content with the team\n", "type": "string", "enum": [ "no_restriction", "only_team_admins" ] }, "endorsed": { "description": "Whether the team has been endorsed\n", "type": "boolean", "example": false } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTeam result = client.teams.createTeam()\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet teamsApiInstance = new Asana.TeamsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The team to create.\nlet opts = { \n 'opt_fields': \"description,edit_team_name_or_description_access_level,edit_team_visibility_or_trash_team_access_level,endorsed,guest_invite_management_access_level,html_description,join_request_management_access_level,member_invite_management_access_level,name,organization,organization.name,permalink_url,team_content_management_access_level,team_member_removal_access_level,visibility\"\n};\nteamsApiInstance.createTeam(body, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.teams.createTeam({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nteams_api_instance = asana.TeamsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The team to create.\nopts = {\n 'opt_fields': \"description,edit_team_name_or_description_access_level,edit_team_visibility_or_trash_team_access_level,endorsed,guest_invite_management_access_level,html_description,join_request_management_access_level,member_invite_management_access_level,name,organization,organization.name,permalink_url,team_content_management_access_level,team_member_removal_access_level,visibility\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a team\n api_response = teams_api_instance.create_team(body, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TeamsApi->create_team: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.teams.create_team({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "teams->createTeam(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.teams.create_team(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 15, "x-moar-complexity-skipped": false } }, "/teams/{team_gid}": { "parameters": [ { "name": "team_gid", "in": "path", "description": "Globally unique identifier for the team.", "required": true, "schema": { "type": "string" }, "example": "159874", "x-env-variable": "team" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a team", "description": "Required scope: teams:read\n\nReturns the full record for a single team.", "tags": [ "Teams" ], "operationId": "getTeam", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "description", "edit_team_name_or_description_access_level", "edit_team_visibility_or_trash_team_access_level", "endorsed", "guest_invite_management_access_level", "html_description", "join_request_management_access_level", "member_invite_management_access_level", "name", "organization", "organization.name", "permalink_url", "team_content_management_access_level", "team_member_removal_access_level", "visibility" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "description", "edit_team_name_or_description_access_level", "edit_team_visibility_or_trash_team_access_level", "endorsed", "guest_invite_management_access_level", "html_description", "join_request_management_access_level", "member_invite_management_access_level", "name", "organization", "organization.name", "permalink_url", "team_content_management_access_level", "team_member_removal_access_level", "visibility" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the record for a single team.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the team.\n", "type": "string", "example": "All developers should be members of this team." }, "html_description": { "description": "[Opt In](/docs/inputoutput-options). The description of the team with formatting as HTML.\n", "type": "string", "example": "All developers should be members of this team." }, "organization": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "description": "The organization/workspace the team belongs to.\n" } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" }, "visibility": { "description": "The visibility of the team to users in the same organization\n", "type": "string", "enum": [ "secret", "request_to_join", "public" ] }, "edit_team_name_or_description_access_level": { "description": "Controls who can edit team name and description\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "edit_team_visibility_or_trash_team_access_level": { "description": "Controls who can edit team visibility and trash teams\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "member_invite_management_access_level": { "description": "Controls who can accept or deny member invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "guest_invite_management_access_level": { "description": "Controls who can accept or deny guest invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "join_request_management_access_level": { "description": "Controls who can accept or deny join team requests for a Membership by Request team. This field can only be updated when the team's `visibility` field is `request_to_join`.\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_member_removal_access_level": { "description": "Controls who can remove team members\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_content_management_access_level": { "description": "Controls who can create and share content with the team\n", "type": "string", "enum": [ "no_restriction", "only_team_admins" ] }, "endorsed": { "description": "Whether the team has been endorsed\n", "type": "boolean", "example": false } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "teams:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTeam result = client.teams.getTeam(teamGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet teamsApiInstance = new Asana.TeamsApi();\nlet team_gid = \"159874\"; // String | Globally unique identifier for the team.\nlet opts = { \n 'opt_fields': \"description,edit_team_name_or_description_access_level,edit_team_visibility_or_trash_team_access_level,endorsed,guest_invite_management_access_level,html_description,join_request_management_access_level,member_invite_management_access_level,name,organization,organization.name,permalink_url,team_content_management_access_level,team_member_removal_access_level,visibility\"\n};\nteamsApiInstance.getTeam(team_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.teams.getTeam(teamGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nteams_api_instance = asana.TeamsApi(api_client)\nteam_gid = \"159874\" # str | Globally unique identifier for the team.\nopts = {\n 'opt_fields': \"description,edit_team_name_or_description_access_level,edit_team_visibility_or_trash_team_access_level,endorsed,guest_invite_management_access_level,html_description,join_request_management_access_level,member_invite_management_access_level,name,organization,organization.name,permalink_url,team_content_management_access_level,team_member_removal_access_level,visibility\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a team\n api_response = teams_api_instance.get_team(team_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TeamsApi->get_team: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.teams.get_team(team_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "teams->getTeam($team_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.teams.get_team(team_gid: 'team_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a team", "description": "Updates a team within the current workspace.", "tags": [ "Teams" ], "operationId": "updateTeam", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "description", "edit_team_name_or_description_access_level", "edit_team_visibility_or_trash_team_access_level", "endorsed", "guest_invite_management_access_level", "html_description", "join_request_management_access_level", "member_invite_management_access_level", "name", "organization", "organization.name", "permalink_url", "team_content_management_access_level", "team_member_removal_access_level", "visibility" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "description", "edit_team_name_or_description_access_level", "edit_team_visibility_or_trash_team_access_level", "endorsed", "guest_invite_management_access_level", "html_description", "join_request_management_access_level", "member_invite_management_access_level", "name", "organization", "organization.name", "permalink_url", "team_content_management_access_level", "team_member_removal_access_level", "visibility" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The team to update.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "properties": { "description": { "description": "The description of the team.\n", "type": "string", "example": "All developers should be members of this team." }, "html_description": { "description": "The description of the team with formatting as HTML.\n", "type": "string", "example": "All developers should be members of this team." }, "organization": { "type": "string", "description": "The organization/workspace the team belongs to. This must be the same organization you are in and cannot be changed once set.\n", "example": "123456789" }, "visibility": { "description": "The visibility of the team to users in the same organization\n", "type": "string", "enum": [ "secret", "request_to_join", "public" ] }, "edit_team_name_or_description_access_level": { "description": "Controls who can edit team name and description\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "edit_team_visibility_or_trash_team_access_level": { "description": "Controls who can edit team visibility and trash teams\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "member_invite_management_access_level": { "description": "Controls who can accept or deny member invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "guest_invite_management_access_level": { "description": "Controls who can accept or deny guest invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "join_request_management_access_level": { "description": "Controls who can accept or deny join team requests for a Membership by Request team. This field can only be updated when the team's `visibility` field is `request_to_join`.\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_member_removal_access_level": { "description": "Controls who can remove team members\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_content_management_access_level": { "description": "Controls who can create and share content with the team\n", "type": "string", "enum": [ "no_restriction", "only_team_admins" ] }, "endorsed": { "description": "Whether the team has been endorsed\n", "type": "boolean", "example": false } } } ] } } } } } }, "responses": { "200": { "description": "Successfully updated the team.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, { "type": "object", "properties": { "description": { "description": "[Opt In](/docs/inputoutput-options). The description of the team.\n", "type": "string", "example": "All developers should be members of this team." }, "html_description": { "description": "[Opt In](/docs/inputoutput-options). The description of the team with formatting as HTML.\n", "type": "string", "example": "All developers should be members of this team." }, "organization": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "description": "The organization/workspace the team belongs to.\n" } ] }, "permalink_url": { "type": "string", "readOnly": true, "description": "A url that points directly to the object within Asana.", "example": "https://app.asana.com/0/resource/123456789/list" }, "visibility": { "description": "The visibility of the team to users in the same organization\n", "type": "string", "enum": [ "secret", "request_to_join", "public" ] }, "edit_team_name_or_description_access_level": { "description": "Controls who can edit team name and description\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "edit_team_visibility_or_trash_team_access_level": { "description": "Controls who can edit team visibility and trash teams\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "member_invite_management_access_level": { "description": "Controls who can accept or deny member invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "guest_invite_management_access_level": { "description": "Controls who can accept or deny guest invites for a given team\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "join_request_management_access_level": { "description": "Controls who can accept or deny join team requests for a Membership by Request team. This field can only be updated when the team's `visibility` field is `request_to_join`.\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_member_removal_access_level": { "description": "Controls who can remove team members\n", "type": "string", "enum": [ "all_team_members", "only_team_admins" ] }, "team_content_management_access_level": { "description": "Controls who can create and share content with the team\n", "type": "string", "enum": [ "no_restriction", "only_team_admins" ] }, "endorsed": { "description": "Whether the team has been endorsed\n", "type": "boolean", "example": false } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nTeam result = client.teams.updateTeam()\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet teamsApiInstance = new Asana.TeamsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The team to update.\nlet team_gid = \"159874\"; // String | Globally unique identifier for the team.\nlet opts = { \n 'opt_fields': \"description,edit_team_name_or_description_access_level,edit_team_visibility_or_trash_team_access_level,endorsed,guest_invite_management_access_level,html_description,join_request_management_access_level,member_invite_management_access_level,name,organization,organization.name,permalink_url,team_content_management_access_level,team_member_removal_access_level,visibility\"\n};\nteamsApiInstance.updateTeam(body, team_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.teams.updateTeam(teamGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nteams_api_instance = asana.TeamsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The team to update.\nteam_gid = \"159874\" # str | Globally unique identifier for the team.\nopts = {\n 'opt_fields': \"description,edit_team_name_or_description_access_level,edit_team_visibility_or_trash_team_access_level,endorsed,guest_invite_management_access_level,html_description,join_request_management_access_level,member_invite_management_access_level,name,organization,organization.name,permalink_url,team_content_management_access_level,team_member_removal_access_level,visibility\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a team\n api_response = teams_api_instance.update_team(body, team_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TeamsApi->update_team: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.teams.update_team(team_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "teams->updateTeam(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.teams.update_team(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 15, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/teams": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get teams in a workspace", "description": "Required scope: teams:read\n\nReturns the compact records for all teams in the workspace visible to the authorized user.", "tags": [ "Teams" ], "operationId": "getTeamsForWorkspace", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "description", "edit_team_name_or_description_access_level", "edit_team_visibility_or_trash_team_access_level", "endorsed", "guest_invite_management_access_level", "html_description", "join_request_management_access_level", "member_invite_management_access_level", "name", "offset", "organization", "organization.name", "path", "permalink_url", "team_content_management_access_level", "team_member_removal_access_level", "uri", "visibility" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "description", "edit_team_name_or_description_access_level", "edit_team_visibility_or_trash_team_access_level", "endorsed", "guest_invite_management_access_level", "html_description", "join_request_management_access_level", "member_invite_management_access_level", "name", "offset", "organization", "organization.name", "path", "permalink_url", "team_content_management_access_level", "team_member_removal_access_level", "uri", "visibility" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Returns the team records for all teams in the organization or workspace accessible to the authenticated user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "teams:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.teams.getTeamsForWorkspace(workspaceGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet teamsApiInstance = new Asana.TeamsApi();\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"description,edit_team_name_or_description_access_level,edit_team_visibility_or_trash_team_access_level,endorsed,guest_invite_management_access_level,html_description,join_request_management_access_level,member_invite_management_access_level,name,offset,organization,organization.name,path,permalink_url,team_content_management_access_level,team_member_removal_access_level,uri,visibility\"\n};\nteamsApiInstance.getTeamsForWorkspace(workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.teams.getTeamsForWorkspace(workspaceGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nteams_api_instance = asana.TeamsApi(api_client)\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"description,edit_team_name_or_description_access_level,edit_team_visibility_or_trash_team_access_level,endorsed,guest_invite_management_access_level,html_description,join_request_management_access_level,member_invite_management_access_level,name,offset,organization,organization.name,path,permalink_url,team_content_management_access_level,team_member_removal_access_level,uri,visibility\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get teams in a workspace\n api_response = teams_api_instance.get_teams_for_workspace(workspace_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TeamsApi->get_teams_for_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.teams.get_teams_for_workspace(workspace_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "teams->getTeamsForWorkspace($workspace_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.teams.get_teams_for_workspace(workspace_gid: 'workspace_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/users/{user_gid}/teams": { "parameters": [ { "name": "user_gid", "in": "path", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "required": true, "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "organization", "in": "query", "description": "The workspace or organization to filter teams on.", "required": true, "schema": { "type": "string" }, "example": "1331" } ], "get": { "summary": "Get teams for a user", "description": "Required scope: teams:read\n\nReturns the compact records for all teams to which the given user is assigned.", "tags": [ "Teams" ], "operationId": "getTeamsForUser", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "description", "edit_team_name_or_description_access_level", "edit_team_visibility_or_trash_team_access_level", "endorsed", "guest_invite_management_access_level", "html_description", "join_request_management_access_level", "member_invite_management_access_level", "name", "offset", "organization", "organization.name", "path", "permalink_url", "team_content_management_access_level", "team_member_removal_access_level", "uri", "visibility" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "description", "edit_team_name_or_description_access_level", "edit_team_visibility_or_trash_team_access_level", "endorsed", "guest_invite_management_access_level", "html_description", "join_request_management_access_level", "member_invite_management_access_level", "name", "offset", "organization", "organization.name", "path", "permalink_url", "team_content_management_access_level", "team_member_removal_access_level", "uri", "visibility" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Returns the team records for all teams in the organization or workspace to which the given user is assigned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "teams:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.teams.getTeamsForUser(userGid, organization)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet teamsApiInstance = new Asana.TeamsApi();\nlet user_gid = \"me\"; // String | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\nlet organization = \"1331\"; // String | The workspace or organization to filter teams on.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"description,edit_team_name_or_description_access_level,edit_team_visibility_or_trash_team_access_level,endorsed,guest_invite_management_access_level,html_description,join_request_management_access_level,member_invite_management_access_level,name,offset,organization,organization.name,path,permalink_url,team_content_management_access_level,team_member_removal_access_level,uri,visibility\"\n};\nteamsApiInstance.getTeamsForUser(user_gid, organization, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.teams.getTeamsForUser(userGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nteams_api_instance = asana.TeamsApi(api_client)\nuser_gid = \"me\" # str | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\norganization = \"1331\" # str | The workspace or organization to filter teams on.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"description,edit_team_name_or_description_access_level,edit_team_visibility_or_trash_team_access_level,endorsed,guest_invite_management_access_level,html_description,join_request_management_access_level,member_invite_management_access_level,name,offset,organization,organization.name,path,permalink_url,team_content_management_access_level,team_member_removal_access_level,uri,visibility\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get teams for a user\n api_response = teams_api_instance.get_teams_for_user(user_gid, organization, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TeamsApi->get_teams_for_user: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.teams.get_teams_for_user(user_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "teams->getTeamsForUser($user_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.teams.get_teams_for_user(user_gid: 'user_gid', organization: ''organization_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/teams/{team_gid}/addUser": { "parameters": [ { "name": "team_gid", "in": "path", "description": "Globally unique identifier for the team.", "required": true, "schema": { "type": "string" }, "example": "159874", "x-env-variable": "team" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add a user to a team", "description": "The user making this call must be a member of the team in order to add others. The user being added must exist in the same organization as the team.\n\nReturns the complete team membership record for the newly added user.", "tags": [ "Teams" ], "operationId": "addUserForTeam", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "is_admin", "is_guest", "is_limited_access", "team", "team.name", "user", "user.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "is_admin", "is_guest", "is_limited_access", "team", "team.name", "user", "user.name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The user to add to the team.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "A user identification object for specification with the addUser/removeUser endpoints.", "properties": { "user": { "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "12345" } } } } } } } }, "responses": { "200": { "description": "Successfully added user to the team.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "This object represents a user's connection to a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team_membership", "x-insert-after": "gid" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "team": { "description": "

Full object requires scope: teams:read

\n\nA *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "team", "x-insert-after": "gid" }, "name": { "description": "The name of the team.", "type": "string", "example": "Marketing" } } }, "is_guest": { "type": "boolean", "description": "Describes if the user is a guest in the team.", "example": false }, "is_limited_access": { "type": "boolean", "readOnly": true, "description": "Describes if the user has limited access to the team.", "example": false }, "is_admin": { "type": "boolean", "description": "Describes if the user is a team admin.", "example": false } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.teams.addUserForTeam(teamGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet teamsApiInstance = new Asana.TeamsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The user to add to the team.\nlet team_gid = \"159874\"; // String | Globally unique identifier for the team.\nlet opts = { \n 'opt_fields': \"is_admin,is_guest,is_limited_access,team,team.name,user,user.name\"\n};\nteamsApiInstance.addUserForTeam(body, team_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.teams.addUserForTeam(teamGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nteams_api_instance = asana.TeamsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The user to add to the team.\nteam_gid = \"159874\" # str | Globally unique identifier for the team.\nopts = {\n 'opt_fields': \"is_admin,is_guest,is_limited_access,team,team.name,user,user.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Add a user to a team\n api_response = teams_api_instance.add_user_for_team(body, team_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TeamsApi->add_user_for_team: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.teams.add_user_for_team(team_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "teams->addUserForTeam($team_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.teams.add_user_for_team(team_gid: 'team_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/teams/{team_gid}/removeUser": { "parameters": [ { "name": "team_gid", "in": "path", "description": "Globally unique identifier for the team.", "required": true, "schema": { "type": "string" }, "example": "159874", "x-env-variable": "team" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Remove a user from a team", "description": "The user making this call must be a member of the team in order to remove themselves or others.", "tags": [ "Teams" ], "operationId": "removeUserForTeam", "requestBody": { "description": "The user to remove from the team.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "A user identification object for specification with the addUser/removeUser endpoints.", "properties": { "user": { "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "12345" } } } } } } } }, "responses": { "200": { "description": "Returns an empty data record", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.teams.removeUserForTeam(teamGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet teamsApiInstance = new Asana.TeamsApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The user to remove from the team.\nlet team_gid = \"159874\"; // String | Globally unique identifier for the team.\n\nteamsApiInstance.removeUserForTeam(body, team_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.teams.removeUserForTeam(teamGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nteams_api_instance = asana.TeamsApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The user to remove from the team.\nteam_gid = \"159874\" # str | Globally unique identifier for the team.\n\n\ntry:\n # Remove a user from a team\n api_response = teams_api_instance.remove_user_for_team(body, team_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TeamsApi->remove_user_for_team: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.teams.remove_user_for_team(team_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "teams->removeUserForTeam($team_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.teams.remove_user_for_team(team_gid: 'team_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/time_periods/{time_period_gid}": { "parameters": [ { "name": "time_period_gid", "in": "path", "description": "Globally unique identifier for the time period.", "required": true, "schema": { "type": "string" }, "example": "917392", "x-env-variable": "time_period" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a time period", "description": "Returns the full record for a single time period.", "tags": [ "Time periods" ], "operationId": "getTimePeriod", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "display_name", "end_on", "parent", "parent.display_name", "parent.end_on", "parent.period", "parent.start_on", "period", "start_on" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "display_name", "end_on", "parent", "parent.display_name", "parent.end_on", "parent.period", "parent.start_on", "period", "start_on" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the record for a single time period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "

Full object requires scope: time_periods:read

\n\nA generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_period", "x-insert-after": "gid" }, "end_on": { "type": "string", "description": "The localized end date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-14" }, "start_on": { "type": "string", "description": "The localized start date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-13" }, "period": { "type": "string", "description": "The cadence and index of the time period.", "enum": [ "FY", "H1", "H2", "Q1", "Q2", "Q3", "Q4" ], "example": "Q1" }, "display_name": { "type": "string", "description": "A string representing the cadence code and the fiscal year.", "example": "Q1 FY22" } } }, { "type": "object", "properties": { "parent": { "allOf": [ { "description": "

Full object requires scope: time_periods:read

\n\nA generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_period", "x-insert-after": "gid" }, "end_on": { "type": "string", "description": "The localized end date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-14" }, "start_on": { "type": "string", "description": "The localized start date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-13" }, "period": { "type": "string", "description": "The cadence and index of the time period.", "enum": [ "FY", "H1", "H2", "Q1", "Q2", "Q3", "Q4" ], "example": "Q1" }, "display_name": { "type": "string", "description": "A string representing the cadence code and the fiscal year.", "example": "Q1 FY22" } } }, { "nullable": true } ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.timeperiods.getTimePeriod(timePeriodGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet timePeriodsApiInstance = new Asana.TimePeriodsApi();\nlet time_period_gid = \"917392\"; // String | Globally unique identifier for the time period.\nlet opts = { \n 'opt_fields': \"display_name,end_on,parent,parent.display_name,parent.end_on,parent.period,parent.start_on,period,start_on\"\n};\ntimePeriodsApiInstance.getTimePeriod(time_period_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.timeperiods.getTimePeriod(timePeriodGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntime_periods_api_instance = asana.TimePeriodsApi(api_client)\ntime_period_gid = \"917392\" # str | Globally unique identifier for the time period.\nopts = {\n 'opt_fields': \"display_name,end_on,parent,parent.display_name,parent.end_on,parent.period,parent.start_on,period,start_on\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a time period\n api_response = time_periods_api_instance.get_time_period(time_period_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TimePeriodsApi->get_time_period: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.time_periods.get_time_period(time_period_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "timeperiods->getTimePeriod($time_period_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.time_periods.get_time_period(time_period_gid: 'time_period_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/time_periods": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get time periods", "description": "Returns compact time period records.", "tags": [ "Time periods" ], "operationId": "getTimePeriods", "parameters": [ { "name": "start_on", "in": "query", "description": "ISO 8601 date string", "schema": { "type": "string", "format": "date" }, "example": "2019-09-15" }, { "name": "end_on", "in": "query", "description": "ISO 8601 date string", "schema": { "type": "string", "format": "date" }, "example": "2019-09-15" }, { "name": "workspace", "in": "query", "required": true, "description": "Globally unique identifier for the workspace.", "schema": { "type": "string" }, "example": "31326" }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "display_name", "end_on", "offset", "parent", "parent.display_name", "parent.end_on", "parent.period", "parent.start_on", "path", "period", "start_on", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "display_name", "end_on", "offset", "parent", "parent.display_name", "parent.end_on", "parent.period", "parent.start_on", "path", "period", "start_on", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested time periods.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "

Full object requires scope: time_periods:read

\n\nA generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_period", "x-insert-after": "gid" }, "end_on": { "type": "string", "description": "The localized end date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-14" }, "start_on": { "type": "string", "description": "The localized start date of the time period in `YYYY-MM-DD` format.", "example": "2019-09-13" }, "period": { "type": "string", "description": "The cadence and index of the time period.", "enum": [ "FY", "H1", "H2", "Q1", "Q2", "Q3", "Q4" ], "example": "Q1" }, "display_name": { "type": "string", "description": "A string representing the cadence code and the fiscal year.", "example": "Q1 FY22" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.timeperiods.getTimePeriods(endOn, startOn, workspace)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet timePeriodsApiInstance = new Asana.TimePeriodsApi();\nlet workspace = \"31326\"; // String | Globally unique identifier for the workspace.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'start_on': \"2019-09-15\", \n 'end_on': \"2019-09-15\", \n 'opt_fields': \"display_name,end_on,offset,parent,parent.display_name,parent.end_on,parent.period,parent.start_on,path,period,start_on,uri\"\n};\ntimePeriodsApiInstance.getTimePeriods(workspace, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.timeperiods.getTimePeriods({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntime_periods_api_instance = asana.TimePeriodsApi(api_client)\nworkspace = \"31326\" # str | Globally unique identifier for the workspace.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'start_on': '2019-09-15', # date | ISO 8601 date string\n 'end_on': '2019-09-15', # date | ISO 8601 date string\n 'opt_fields': \"display_name,end_on,offset,parent,parent.display_name,parent.end_on,parent.period,parent.start_on,path,period,start_on,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get time periods\n api_response = time_periods_api_instance.get_time_periods(workspace, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TimePeriodsApi->get_time_periods: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.time_periods.get_time_periods({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "timeperiods->getTimePeriods(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.time_periods.get_time_periods(workspace: ''workspace_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/tasks/{task_gid}/time_tracking_entries": { "parameters": [ { "name": "task_gid", "in": "path", "required": true, "description": "The task to operate on.", "schema": { "type": "string" }, "example": "321654", "x-env-variable": "task" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get time tracking entries for a task", "description": "Required scope: time_tracking_entries:read\n\nReturns time tracking entries for a given task.", "tags": [ "Time tracking entries" ], "operationId": "getTimeTrackingEntriesForTask", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "attributable_to", "attributable_to.name", "created_by", "created_by.name", "duration_minutes", "entered_on", "offset", "path", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "attributable_to", "attributable_to.name", "created_by", "created_by.name", "duration_minutes", "entered_on", "offset", "path", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested time tracking entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_tracking_entry", "x-insert-after": "gid" }, "duration_minutes": { "description": "Time in minutes tracked by the entry.", "type": "integer", "example": 12 }, "entered_on": { "description": "The day that this entry is logged on.", "type": "string", "format": "date", "example": "2015-03-14" }, "attributable_to": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The attributable to project specifies which project's budget a time entry should be counted toward, if the task belongs to more than one project. If it only belongs to one project, it should be that project." } ] }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "time_tracking_entries:read" ] } ], "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet timeTrackingEntriesApiInstance = new Asana.TimeTrackingEntriesApi();\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"attributable_to,attributable_to.name,created_by,created_by.name,duration_minutes,entered_on,offset,path,uri\"\n};\ntimeTrackingEntriesApiInstance.getTimeTrackingEntriesForTask(task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.timetrackingentries.getTimeTrackingEntriesForTask(taskGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntime_tracking_entries_api_instance = asana.TimeTrackingEntriesApi(api_client)\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"attributable_to,attributable_to.name,created_by,created_by.name,duration_minutes,entered_on,offset,path,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get time tracking entries for a task\n api_response = time_tracking_entries_api_instance.get_time_tracking_entries_for_task(task_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TimeTrackingEntriesApi->get_time_tracking_entries_for_task: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.time_tracking_entries.get_time_tracking_entries_for_task(task_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Create a time tracking entry", "description": "Creates a time tracking entry on a given task.\n\nReturns the record of the newly created time tracking entry.", "tags": [ "Time tracking entries" ], "operationId": "createTimeTrackingEntry", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "approval_status", "attributable_to", "attributable_to.name", "billable_status", "created_at", "created_by", "created_by.name", "description", "duration_minutes", "entered_on", "task", "task.created_by", "task.name", "task.resource_subtype" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "approval_status", "attributable_to", "attributable_to.name", "billable_status", "created_at", "created_by", "created_by.name", "description", "duration_minutes", "entered_on", "task", "task.created_by", "task.name", "task.resource_subtype" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "Information about the time tracking entry.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "duration_minutes": { "description": "Time in minutes tracked by the entry. Must be greater than 0", "type": "integer", "example": 12 }, "entered_on": { "description": "*Optional*. The day that this entry is logged on. Defaults to today if not specified", "type": "string", "format": "date", "example": "2023-03-19" }, "attributable_to": { "type": "string", "description": "*Optional*. The gid of the project which the time is attributable to.", "example": "987654" } } } } } } } }, "responses": { "201": { "description": "Successfully created a time tracking entry for the task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_tracking_entry", "x-insert-after": "gid" }, "duration_minutes": { "description": "Time in minutes tracked by the entry.", "type": "integer", "example": 12 }, "entered_on": { "description": "The day that this entry is logged on.", "type": "string", "format": "date", "example": "2015-03-14" }, "attributable_to": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The attributable to project specifies which project's budget a time entry should be counted toward, if the task belongs to more than one project. If it only belongs to one project, it should be that project." } ] }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, { "type": "object", "properties": { "task": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "approval_status": { "description": "*Optional*. The current approval status of the entry.", "type": "string", "readOnly": true, "enum": [ "DRAFT", "SUBMITTED", "APPROVED", "REJECTED" ], "example": "DRAFT" }, "billable_status": { "description": "*Optional*. The current billable status of the entry.", "type": "string", "readOnly": true, "enum": [ "billable", "nonBillable", "notApplicable" ], "example": "billable" }, "description": { "description": "*Optional*. The description of the entry.", "type": "string", "readOnly": true, "example": "My description of work done on this entry" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet timeTrackingEntriesApiInstance = new Asana.TimeTrackingEntriesApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | Information about the time tracking entry.\nlet task_gid = \"321654\"; // String | The task to operate on.\nlet opts = { \n 'opt_fields': \"approval_status,attributable_to,attributable_to.name,billable_status,created_at,created_by,created_by.name,description,duration_minutes,entered_on,task,task.created_by,task.name,task.resource_subtype\"\n};\ntimeTrackingEntriesApiInstance.createTimeTrackingEntry(body, task_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.timetrackingentries.createTimeTrackingEntry(taskGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntime_tracking_entries_api_instance = asana.TimeTrackingEntriesApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | Information about the time tracking entry.\ntask_gid = \"321654\" # str | The task to operate on.\nopts = {\n 'opt_fields': \"approval_status,attributable_to,attributable_to.name,billable_status,created_at,created_by,created_by.name,description,duration_minutes,entered_on,task,task.created_by,task.name,task.resource_subtype\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Create a time tracking entry\n api_response = time_tracking_entries_api_instance.create_time_tracking_entry(body, task_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TimeTrackingEntriesApi->create_time_tracking_entry: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.time_tracking_entries.create_time_tracking_entry(task_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 3, "x-moar-complexity-skipped": false } }, "/time_tracking_entries/{time_tracking_entry_gid}": { "parameters": [ { "name": "time_tracking_entry_gid", "in": "path", "description": "Globally unique identifier for the time tracking entry.", "required": true, "schema": { "type": "string" }, "example": "917392", "x-env-variable": "time_tracking_entry" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a time tracking entry", "description": "Required scope: time_tracking_entries:read\n\nReturns the complete time tracking entry record for a single time tracking entry.", "tags": [ "Time tracking entries" ], "operationId": "getTimeTrackingEntry", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "approval_status", "attributable_to", "attributable_to.name", "billable_status", "created_at", "created_by", "created_by.name", "description", "duration_minutes", "entered_on", "task", "task.created_by", "task.name", "task.resource_subtype" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "approval_status", "attributable_to", "attributable_to.name", "billable_status", "created_at", "created_by", "created_by.name", "description", "duration_minutes", "entered_on", "task", "task.created_by", "task.name", "task.resource_subtype" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested time tracking entry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_tracking_entry", "x-insert-after": "gid" }, "duration_minutes": { "description": "Time in minutes tracked by the entry.", "type": "integer", "example": 12 }, "entered_on": { "description": "The day that this entry is logged on.", "type": "string", "format": "date", "example": "2015-03-14" }, "attributable_to": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The attributable to project specifies which project's budget a time entry should be counted toward, if the task belongs to more than one project. If it only belongs to one project, it should be that project." } ] }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, { "type": "object", "properties": { "task": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "approval_status": { "description": "*Optional*. The current approval status of the entry.", "type": "string", "readOnly": true, "enum": [ "DRAFT", "SUBMITTED", "APPROVED", "REJECTED" ], "example": "DRAFT" }, "billable_status": { "description": "*Optional*. The current billable status of the entry.", "type": "string", "readOnly": true, "enum": [ "billable", "nonBillable", "notApplicable" ], "example": "billable" }, "description": { "description": "*Optional*. The description of the entry.", "type": "string", "readOnly": true, "example": "My description of work done on this entry" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "time_tracking_entries:read" ] } ], "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet timeTrackingEntriesApiInstance = new Asana.TimeTrackingEntriesApi();\nlet time_tracking_entry_gid = \"917392\"; // String | Globally unique identifier for the time tracking entry.\nlet opts = { \n 'opt_fields': \"approval_status,attributable_to,attributable_to.name,billable_status,created_at,created_by,created_by.name,description,duration_minutes,entered_on,task,task.created_by,task.name,task.resource_subtype\"\n};\ntimeTrackingEntriesApiInstance.getTimeTrackingEntry(time_tracking_entry_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.timetrackingentries.getTimeTrackingEntry(timeTrackingEntryGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntime_tracking_entries_api_instance = asana.TimeTrackingEntriesApi(api_client)\ntime_tracking_entry_gid = \"917392\" # str | Globally unique identifier for the time tracking entry.\nopts = {\n 'opt_fields': \"approval_status,attributable_to,attributable_to.name,billable_status,created_at,created_by,created_by.name,description,duration_minutes,entered_on,task,task.created_by,task.name,task.resource_subtype\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a time tracking entry\n api_response = time_tracking_entries_api_instance.get_time_tracking_entry(time_tracking_entry_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TimeTrackingEntriesApi->get_time_tracking_entry: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.time_tracking_entries.get_time_tracking_entry(time_tracking_entry_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a time tracking entry", "description": "A specific, existing time tracking entry can be updated by making a `PUT` request on\nthe URL for that time tracking entry. Only the fields provided in the `data` block\nwill be updated; any unspecified fields will remain unchanged.\n\nWhen using this method, it is best to specify only those fields you wish\nto change, or else you may overwrite changes made by another user since\nyou last retrieved the task.\n\nReturns the complete updated time tracking entry record.", "tags": [ "Time tracking entries" ], "operationId": "updateTimeTrackingEntry", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "approval_status", "attributable_to", "attributable_to.name", "billable_status", "created_at", "created_by", "created_by.name", "description", "duration_minutes", "entered_on", "task", "task.created_by", "task.name", "task.resource_subtype" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "approval_status", "attributable_to", "attributable_to.name", "billable_status", "created_at", "created_by", "created_by.name", "description", "duration_minutes", "entered_on", "task", "task.created_by", "task.name", "task.resource_subtype" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The updated fields for the time tracking entry.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "duration_minutes": { "description": "*Optional*. Time in minutes tracked by the entry", "type": "integer", "example": 12 }, "entered_on": { "description": "*Optional*. The day that this entry is logged on. Defaults to today if no day specified", "type": "string", "format": "date", "example": "2023-03-19" }, "attributable_to": { "type": "string", "description": "*Optional*. The gid of the project which the time is attributable to.", "example": "987654" } } } } } } } }, "responses": { "200": { "description": "Successfully updated the time tracking entry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_tracking_entry", "x-insert-after": "gid" }, "duration_minutes": { "description": "Time in minutes tracked by the entry.", "type": "integer", "example": 12 }, "entered_on": { "description": "The day that this entry is logged on.", "type": "string", "format": "date", "example": "2015-03-14" }, "attributable_to": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The attributable to project specifies which project's budget a time entry should be counted toward, if the task belongs to more than one project. If it only belongs to one project, it should be that project." } ] }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } }, { "type": "object", "properties": { "task": { "description": "The *task* is the basic object around which many operations in Asana are centered.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the task.", "type": "string", "example": "Bug Task" }, "resource_subtype": { "type": "string", "description": "The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.\nThe resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.", "enum": [ "default_task", "milestone", "approval" ], "example": "default_task" }, "created_by": { "type": "object", "readOnly": true, "description": "[Opt In](/docs/inputoutput-options). A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "properties": { "gid": { "description": "Globally unique identifier of the resource.", "type": "string", "example": "1111" }, "resource_type": { "description": "The type of resource.", "type": "string", "example": "user" } } } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "approval_status": { "description": "*Optional*. The current approval status of the entry.", "type": "string", "readOnly": true, "enum": [ "DRAFT", "SUBMITTED", "APPROVED", "REJECTED" ], "example": "DRAFT" }, "billable_status": { "description": "*Optional*. The current billable status of the entry.", "type": "string", "readOnly": true, "enum": [ "billable", "nonBillable", "notApplicable" ], "example": "billable" }, "description": { "description": "*Optional*. The description of the entry.", "type": "string", "readOnly": true, "example": "My description of work done on this entry" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet timeTrackingEntriesApiInstance = new Asana.TimeTrackingEntriesApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The updated fields for the time tracking entry.\nlet time_tracking_entry_gid = \"917392\"; // String | Globally unique identifier for the time tracking entry.\nlet opts = { \n 'opt_fields': \"approval_status,attributable_to,attributable_to.name,billable_status,created_at,created_by,created_by.name,description,duration_minutes,entered_on,task,task.created_by,task.name,task.resource_subtype\"\n};\ntimeTrackingEntriesApiInstance.updateTimeTrackingEntry(body, time_tracking_entry_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.timetrackingentries.updateTimeTrackingEntry(timeTrackingEntryGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntime_tracking_entries_api_instance = asana.TimeTrackingEntriesApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The updated fields for the time tracking entry.\ntime_tracking_entry_gid = \"917392\" # str | Globally unique identifier for the time tracking entry.\nopts = {\n 'opt_fields': \"approval_status,attributable_to,attributable_to.name,billable_status,created_at,created_by,created_by.name,description,duration_minutes,entered_on,task,task.created_by,task.name,task.resource_subtype\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a time tracking entry\n api_response = time_tracking_entries_api_instance.update_time_tracking_entry(body, time_tracking_entry_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TimeTrackingEntriesApi->update_time_tracking_entry: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.time_tracking_entries.update_time_tracking_entry(time_tracking_entry_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 3, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a time tracking entry", "description": "A specific, existing time tracking entry can be deleted by making a `DELETE` request on\nthe URL for that time tracking entry.\n\nReturns an empty data record.", "tags": [ "Time tracking entries" ], "operationId": "deleteTimeTrackingEntry", "responses": { "200": { "description": "Successfully deleted the specified time tracking entry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet timeTrackingEntriesApiInstance = new Asana.TimeTrackingEntriesApi();\nlet time_tracking_entry_gid = \"917392\"; // String | Globally unique identifier for the time tracking entry.\n\ntimeTrackingEntriesApiInstance.deleteTimeTrackingEntry(time_tracking_entry_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.timetrackingentries.deleteTimeTrackingEntry(timeTrackingEntryGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntime_tracking_entries_api_instance = asana.TimeTrackingEntriesApi(api_client)\ntime_tracking_entry_gid = \"917392\" # str | Globally unique identifier for the time tracking entry.\n\n\ntry:\n # Delete a time tracking entry\n api_response = time_tracking_entries_api_instance.delete_time_tracking_entry(time_tracking_entry_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling TimeTrackingEntriesApi->delete_time_tracking_entry: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.time_tracking_entries.delete_time_tracking_entry(time_tracking_entry_gid, opt_pretty=True)", "name": "python-sdk-v3" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/time_tracking_entries": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get multiple time tracking entries", "description": "Required scope: time_tracking_entries:read\n\nReturns a list of time tracking entries filtered to a task, attributed project, portfolio or user.", "tags": [ "Time tracking entries" ], "operationId": "getTimeTrackingEntries", "parameters": [ { "name": "task", "in": "query", "description": "Globally unique identifier for the task to filter time tracking entries by.", "schema": { "type": "string" }, "example": "12345" }, { "name": "attributable_to", "in": "query", "description": "Globally unique identifier for the project the time tracking entries are attributed to.", "schema": { "type": "string" }, "example": "12345" }, { "name": "portfolio", "in": "query", "description": "Globally unique identifier for the portfolio to filter time tracking entries by.", "schema": { "type": "string" }, "example": "12345" }, { "name": "user", "in": "query", "description": "Globally unique identifier for the user to filter time tracking entries by.", "schema": { "type": "string" }, "example": "12345" }, { "name": "workspace", "in": "query", "description": "Globally unique identifier for the workspace.", "schema": { "type": "string" }, "example": "98765" }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "attributable_to", "attributable_to.name", "created_by", "created_by.name", "duration_minutes", "entered_on", "offset", "path", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "attributable_to", "attributable_to.name", "created_by", "created_by.name", "duration_minutes", "entered_on", "offset", "path", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested time tracking entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "time_tracking_entry", "x-insert-after": "gid" }, "duration_minutes": { "description": "Time in minutes tracked by the entry.", "type": "integer", "example": 12 }, "entered_on": { "description": "The day that this entry is logged on.", "type": "string", "format": "date", "example": "2015-03-14" }, "attributable_to": { "allOf": [ { "description": "A *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "project", "x-insert-after": "gid" }, "name": { "description": "Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.", "type": "string", "example": "Stuff to buy" } } }, { "type": "object", "description": "The attributable to project specifies which project's budget a time entry should be counted toward, if the task belongs to more than one project. If it only belongs to one project, it should be that project." } ] }, "created_by": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "time_tracking_entries:read" ] } ], "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet timeTrackingEntriesApiInstance = new Asana.TimeTrackingEntriesApi();\nlet opts = { \n 'task': \"12345\", \n 'attributable_to': \"12345\", \n 'portfolio': \"12345\", \n 'user': \"12345\", \n 'workspace': \"98765\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"attributable_to,attributable_to.name,created_by,created_by.name,duration_minutes,entered_on,offset,path,uri\"\n};\ntimeTrackingEntriesApiInstance.getTimeTrackingEntries(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntime_tracking_entries_api_instance = asana.TimeTrackingEntriesApi(api_client)\nopts = {\n 'task': \"12345\", # str | Globally unique identifier for the task to filter time tracking entries by.\n 'attributable_to': \"12345\", # str | Globally unique identifier for the project the time tracking entries are attributed to.\n 'portfolio': \"12345\", # str | Globally unique identifier for the portfolio to filter time tracking entries by.\n 'user': \"12345\", # str | Globally unique identifier for the user to filter time tracking entries by.\n 'workspace': \"98765\", # str | Globally unique identifier for the workspace.\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"attributable_to,attributable_to.name,created_by,created_by.name,duration_minutes,entered_on,offset,path,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple time tracking entries\n api_response = time_tracking_entries_api_instance.get_time_tracking_entries(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TimeTrackingEntriesApi->get_time_tracking_entries: %s\\n\" % e)", "name": "python-sdk-v5" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/typeahead": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "resource_type", "in": "query", "description": "The type of values the typeahead should return. You can choose from one of the following: `custom_field`, `goal`, `project`, `project_template`, `portfolio`, `tag`, `task`, `team`, and `user`. Note that unlike in the names of endpoints, the types listed here are in singular form (e.g. `task`). Using multiple types is not yet supported.", "required": true, "schema": { "type": "string", "enum": [ "custom_field", "goal", "project", "project_template", "portfolio", "tag", "task", "team", "user" ], "default": "user" } }, { "name": "type", "in": "query", "description": "*Deprecated: new integrations should prefer the resource_type field.*", "required": false, "schema": { "type": "string", "enum": [ "custom_field", "portfolio", "project", "tag", "task", "user" ], "default": "user" } }, { "name": "query", "in": "query", "description": "The string that will be used to search for relevant objects. If an empty string is passed in, the API will return results.", "schema": { "type": "string" }, "example": "Greg" }, { "name": "count", "in": "query", "description": "The number of results to return. The default is 20 if this parameter is omitted, with a minimum of 1 and a maximum of 100. If there are fewer results found than requested, all will be returned.", "schema": { "type": "integer" }, "example": 20 }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get objects via typeahead", "description": "Required scope: workspace.typeahead:read\n\nRetrieves objects in the workspace based via an auto-completion/typeahead\nsearch algorithm. This feature is meant to provide results quickly, so do\nnot rely on this API to provide extremely accurate search results. The\nresult set is limited to a single page of results with a maximum size, so\nyou won\u2019t be able to fetch large numbers of results.\n\nThe typeahead search API provides search for objects from a single\nworkspace. This endpoint should be used to query for objects when\ncreating an auto-completion/typeahead search feature. This API is meant\nto provide results quickly and should not be relied upon for accurate or\nexhaustive search results. The results sets are limited in size and\ncannot be paginated.\n\nQueries return a compact representation of each object which is typically\nthe gid and name fields. Interested in a specific set of fields or all of\nthe fields?! Of course you are. Use field selectors to manipulate what\ndata is included in a response.\n\nResources with type `user` are returned in order of most contacted to\nleast contacted. This is determined by task assignments, adding the user\nto projects, and adding the user as a follower to tasks, messages,\netc.\n\nResources with type `project` are returned in order of recency. This is\ndetermined when the user visits the project, is added to the project, and\ncompletes tasks in the project.\n\nResources with type `task` are returned with priority placed on tasks\nthe user is following, but no guarantee on the order of those tasks.\n\nResources with type `project_template` are returned with priority\nplaced on favorited project templates.\n\nLeaving the `query` string empty or omitted will give you results, still\nfollowing the resource ordering above. This could be used to list users or\nprojects that are relevant for the requesting user's api token.", "tags": [ "Typeahead" ], "operationId": "typeaheadForWorkspace", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved objects via a typeahead search algorithm.", "content": { "application/json": { "schema": { "type": "object", "description": "A generic list of objects, such as those returned by the typeahead search endpoint.", "properties": { "data": { "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "workspace.typeahead:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.typeahead.typeaheadForWorkspace(workspaceGid, count, query, type, resourceType)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet typeaheadApiInstance = new Asana.TypeaheadApi();\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet resource_type = \"user\"; // String | The type of values the typeahead should return. You can choose from one of the following: `custom_field`, `goal`, `project`, `project_template`, `portfolio`, `tag`, `task`, `team`, and `user`. Note that unlike in the names of endpoints, the types listed here are in singular form (e.g. `task`). Using multiple types is not yet supported.\nlet opts = { \n 'type': \"user\", \n 'query': \"Greg\", \n 'count': 20, \n 'opt_fields': \"name\"\n};\ntypeaheadApiInstance.typeaheadForWorkspace(workspace_gid, resource_type, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.typeahead.typeaheadForWorkspace(workspaceGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\ntypeahead_api_instance = asana.TypeaheadApi(api_client)\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nresource_type = \"user\" # str | The type of values the typeahead should return. You can choose from one of the following: `custom_field`, `goal`, `project`, `project_template`, `portfolio`, `tag`, `task`, `team`, and `user`. Note that unlike in the names of endpoints, the types listed here are in singular form (e.g. `task`). Using multiple types is not yet supported.\nopts = {\n 'type': \"user\", # str | *Deprecated: new integrations should prefer the resource_type field.*\n 'query': \"Greg\", # str | The string that will be used to search for relevant objects. If an empty string is passed in, the API will return results.\n 'count': 20, # int | The number of results to return. The default is 20 if this parameter is omitted, with a minimum of 1 and a maximum of 100. If there are fewer results found than requested, all will be returned.\n 'opt_fields': \"name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get objects via typeahead\n api_response = typeahead_api_instance.typeahead_for_workspace(workspace_gid, resource_type, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling TypeaheadApi->typeahead_for_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.typeahead.typeahead_for_workspace(workspace_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "typeahead->typeaheadForWorkspace($workspace_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.typeahead.typeahead_for_workspace(workspace_gid: 'workspace_gid', resource_type: ''resource_type_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/user_task_lists/{user_task_list_gid}": { "parameters": [ { "name": "user_task_list_gid", "in": "path", "description": "Globally unique identifier for the user task list.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "user_task_list" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a user task list", "description": "Required scope: tasks:read\n\nReturns the full record for a user task list.", "tags": [ "User task lists" ], "operationId": "getUserTaskList", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "name", "owner", "workspace" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "owner", "workspace" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the user task list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A user task list represents the tasks assigned to a particular user. It provides API access to a user\u2019s [My tasks](https://asana.com/guide/help/fundamentals/my-tasks) view in Asana.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user_task_list", "x-insert-after": "gid" }, "name": { "description": "The name of the user task list.", "type": "string", "example": "My tasks in My Workspace" }, "owner": { "description": "The owner of the user task list, i.e. the person whose My Tasks is represented by this resource.", "readOnly": true, "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } ] }, "workspace": { "description": "The workspace in which the user task list is located.", "readOnly": true, "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } } ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nUserTaskList result = client.usertasklists.getUserTaskList(userTaskListGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet userTaskListsApiInstance = new Asana.UserTaskListsApi();\nlet user_task_list_gid = \"12345\"; // String | Globally unique identifier for the user task list.\nlet opts = { \n 'opt_fields': \"name,owner,workspace\"\n};\nuserTaskListsApiInstance.getUserTaskList(user_task_list_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.usertasklists.getUserTaskList(userTaskListGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nuser_task_lists_api_instance = asana.UserTaskListsApi(api_client)\nuser_task_list_gid = \"12345\" # str | Globally unique identifier for the user task list.\nopts = {\n 'opt_fields': \"name,owner,workspace\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a user task list\n api_response = user_task_lists_api_instance.get_user_task_list(user_task_list_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling UserTaskListsApi->get_user_task_list: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.user_task_lists.get_user_task_list(user_task_list_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "usertasklists->getUserTaskList($user_task_list_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.user_task_lists.get_user_task_list(user_task_list_gid: 'user_task_list_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/users/{user_gid}/user_task_list": { "parameters": [ { "name": "user_gid", "in": "path", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "required": true, "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "workspace", "in": "query", "required": true, "description": "The workspace in which to get the user task list.", "schema": { "type": "string" }, "example": "1234" } ], "get": { "summary": "Get a user's task list", "description": "Required scope: tasks:read\n\nReturns the full record for a user's task list.", "tags": [ "User task lists" ], "operationId": "getUserTaskListForUser", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "name", "owner", "workspace" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "owner", "workspace" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the user's task list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A user task list represents the tasks assigned to a particular user. It provides API access to a user\u2019s [My tasks](https://asana.com/guide/help/fundamentals/my-tasks) view in Asana.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user_task_list", "x-insert-after": "gid" }, "name": { "description": "The name of the user task list.", "type": "string", "example": "My tasks in My Workspace" }, "owner": { "description": "The owner of the user task list, i.e. the person whose My Tasks is represented by this resource.", "readOnly": true, "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } ] }, "workspace": { "description": "The workspace in which the user task list is located.", "readOnly": true, "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } } ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "tasks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nUserTaskList result = client.usertasklists.getUserTaskListForUser(userGid, workspace)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet userTaskListsApiInstance = new Asana.UserTaskListsApi();\nlet user_gid = \"me\"; // String | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\nlet workspace = \"1234\"; // String | The workspace in which to get the user task list.\nlet opts = { \n 'opt_fields': \"name,owner,workspace\"\n};\nuserTaskListsApiInstance.getUserTaskListForUser(user_gid, workspace, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.usertasklists.getUserTaskListForUser(userGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nuser_task_lists_api_instance = asana.UserTaskListsApi(api_client)\nuser_gid = \"me\" # str | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\nworkspace = \"1234\" # str | The workspace in which to get the user task list.\nopts = {\n 'opt_fields': \"name,owner,workspace\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a user's task list\n api_response = user_task_lists_api_instance.get_user_task_list_for_user(user_gid, workspace, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling UserTaskListsApi->get_user_task_list_for_user: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.user_task_lists.get_user_task_list_for_user(user_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "usertasklists->getUserTaskListForUser($user_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.user_task_lists.get_user_task_list_for_user(user_gid: 'user_gid', workspace: ''workspace_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/users": { "parameters": [ { "name": "workspace", "in": "query", "description": "The workspace or organization ID to filter users on.", "schema": { "type": "string" }, "example": "1331" }, { "name": "team", "in": "query", "description": "The team ID to filter users on.", "schema": { "type": "string" }, "example": "15627" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get multiple users", "description": "Required scope: users:read\n\nReturns the user records for all users in all workspaces and organizations accessible to the authenticated user. Accepts an optional workspace ID parameter.\nResults are sorted by user ID.", "tags": [ "Users" ], "operationId": "getUsers", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "email", "name", "offset", "path", "photo", "photo.image_1024x1024", "photo.image_128x128", "photo.image_21x21", "photo.image_27x27", "photo.image_36x36", "photo.image_60x60", "uri", "workspaces", "workspaces.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "email", "name", "offset", "path", "photo", "photo.image_1024x1024", "photo.image_128x128", "photo.image_21x21", "photo.image_27x27", "photo.image_36x36", "photo.image_60x60", "uri", "workspaces", "workspaces.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested user records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "users:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.users.getUsers(team, workspace)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet usersApiInstance = new Asana.UsersApi();\nlet opts = { \n 'workspace': \"1331\", \n 'team': \"15627\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,email,name,offset,path,photo,photo.image_1024x1024,photo.image_128x128,photo.image_21x21,photo.image_27x27,photo.image_36x36,photo.image_60x60,uri,workspaces,workspaces.name\"\n};\nusersApiInstance.getUsers(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.users.getUsers({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nusers_api_instance = asana.UsersApi(api_client)\nopts = {\n 'workspace': \"1331\", # str | The workspace or organization ID to filter users on.\n 'team': \"15627\", # str | The team ID to filter users on.\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,email,name,offset,path,photo,photo.image_1024x1024,photo.image_128x128,photo.image_21x21,photo.image_27x27,photo.image_36x36,photo.image_60x60,uri,workspaces,workspaces.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple users\n api_response = users_api_instance.get_users(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling UsersApi->get_users: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.users.get_users({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "users->getUsers(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.users.get_users(param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/users/{user_gid}": { "parameters": [ { "name": "user_gid", "in": "path", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "required": true, "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a user", "description": "Required scope: users:read\n\nReturns the full user record for the single user with the provided ID.", "tags": [ "Users" ], "operationId": "getUser", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "email", "name", "photo", "photo.image_1024x1024", "photo.image_128x128", "photo.image_21x21", "photo.image_27x27", "photo.image_36x36", "photo.image_60x60", "workspaces", "workspaces.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "email", "name", "photo", "photo.image_1024x1024", "photo.image_128x128", "photo.image_21x21", "photo.image_27x27", "photo.image_36x36", "photo.image_60x60", "workspaces", "workspaces.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Returns the user specified.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "properties": { "email": { "type": "string", "format": "email", "readOnly": true, "description": "The user's email address.", "example": "gsanchez@example.com" }, "photo": { "type": "object", "nullable": true, "properties": { "image_21x21": { "type": "string", "format": "uri", "description": "PNG image of the user at 21x21 pixels." }, "image_27x27": { "type": "string", "format": "uri", "description": "PNG image of the user at 27x27 pixels." }, "image_36x36": { "type": "string", "format": "uri", "description": "PNG image of the user at 36x36 pixels." }, "image_60x60": { "type": "string", "format": "uri", "description": "PNG image of the user at 60x60 pixels." }, "image_128x128": { "type": "string", "format": "uri", "description": "PNG image of the user at 128x128 pixels." }, "image_1024x1024": { "type": "string", "format": "uri", "description": "JPEG image of the user at 1024x1024 pixels." } }, "readOnly": true, "description": "A map of the user's profile photo in various sizes, or null if no photo is set. Sizes provided are 21, 27, 36, 60, 128, and 1024. All images are in PNG format, except for 1024 (which is in JPEG format).", "example": { "image_21x21": "https://...", "image_27x27": "https://...", "image_36x36": "https://...", "image_60x60": "https://...", "image_128x128": "https://...", "image_1024x1024": "https://..." } } } } ] }, { "type": "object", "properties": { "workspaces": { "description": "Workspaces and organizations this user may access.\nNote\\: The API will only return workspaces and organizations that also contain the authenticated user.", "readOnly": true, "type": "array", "items": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } } }, "custom_fields": { "description": "Array of Custom Fields.", "type": "array", "items": { "description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "custom_field", "x-insert-after": "gid" }, "name": { "description": "The name of the custom field.", "type": "string", "example": "Status" }, "type": { "description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n", "type": "string", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people" ] }, "enum_options": { "description": "*Conditional*. Only relevant for custom fields of type `enum` or `multi_enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](/reference/createenumoptionforcustomfield).", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "enabled": { "description": "*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).\nDetermines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).", "type": "boolean", "readOnly": true, "example": true }, "representation_type": { "description": "This field tells the type of the custom field.", "type": "string", "example": "number", "readOnly": true, "enum": [ "text", "enum", "multi_enum", "number", "date", "people", "formula", "custom_id" ] }, "id_prefix": { "description": "This field is the unique custom ID string for the custom field.", "type": "string", "nullable": true, "example": "ID" }, "input_restrictions": { "description": "*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.", "type": "array", "items": { "type": "string" }, "example": "task" }, "is_formula_field": { "description": "*Conditional*. This flag describes whether a custom field is a formula custom field.", "type": "boolean", "example": false }, "date_value": { "description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.", "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "A string representing the date in YYYY-MM-DD format.", "example": "2024-08-23" }, "date_time": { "type": "string", "description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.", "example": "2024-08-23T22:00:00.000Z" } } }, "enum_value": { "allOf": [ { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } }, { "type": "object", "nullable": true, "description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field." } ] }, "multi_enum_values": { "description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.", "type": "array", "items": { "description": "Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.\n\nYou can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.\n\n**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.\n\nOn creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to \u201ctrashing\u201d the enum option in the Asana web app within the \u201cEdit Fields\u201d dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.\n\nEnum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.\n\nAn enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "enum_option", "x-insert-after": "gid" }, "name": { "description": "The name of the enum option.", "type": "string", "example": "Low" }, "enabled": { "description": "Whether or not the enum option is a selectable value for the custom field.", "type": "boolean", "example": true }, "color": { "description": "The color of the enum option. Defaults to `none`.", "type": "string", "example": "blue" } } } }, "number_value": { "description": "*Conditional*. This number is the value of a `number` custom field.", "type": "number", "nullable": true, "example": 5.2 }, "text_value": { "description": "*Conditional*. This string is the value of a `text` custom field.", "type": "string", "nullable": true, "example": "Some Value" }, "display_value": { "description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.", "type": "string", "readOnly": true, "example": "blue", "nullable": true } } } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "users:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nUser result = client.users.getUser(userGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet usersApiInstance = new Asana.UsersApi();\nlet user_gid = \"me\"; // String | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\nlet opts = { \n 'opt_fields': \"custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,email,name,photo,photo.image_1024x1024,photo.image_128x128,photo.image_21x21,photo.image_27x27,photo.image_36x36,photo.image_60x60,workspaces,workspaces.name\"\n};\nusersApiInstance.getUser(user_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.users.getUser(userGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nusers_api_instance = asana.UsersApi(api_client)\nuser_gid = \"me\" # str | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\nopts = {\n 'opt_fields': \"custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,email,name,photo,photo.image_1024x1024,photo.image_128x128,photo.image_21x21,photo.image_27x27,photo.image_36x36,photo.image_60x60,workspaces,workspaces.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a user\n api_response = users_api_instance.get_user(user_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling UsersApi->get_user: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.users.get_user(user_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "users->getUser($user_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.users.get_user(user_gid: 'user_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/users/{user_gid}/favorites": { "parameters": [ { "name": "user_gid", "in": "path", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "required": true, "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "resource_type", "in": "query", "required": true, "description": "The resource type of favorites to be returned.", "schema": { "type": "string", "enum": [ "portfolio", "project", "tag", "task", "user", "project_template" ], "default": "project" } }, { "name": "workspace", "in": "query", "required": true, "description": "The workspace in which to get favorites.", "schema": { "type": "string" }, "example": "1234" } ], "get": { "summary": "Get a user's favorites", "description": "Required scope: users:read\n\nReturns all of a user's favorites within a specified workspace and of a given type. The results are ordered exactly as they appear in the user's Asana sidebar in the web application. Note that this endpoint currently only returns favorites for the current user (i.e., the user associated with the authentication token).", "tags": [ "Users" ], "operationId": "getFavoritesForUser", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "name", "offset", "path", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "offset", "path", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Returns the specified user's favorites.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "users:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.users.getFavoritesForUser(userGid, workspace, resourceType)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet usersApiInstance = new Asana.UsersApi();\nlet user_gid = \"me\"; // String | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\nlet resource_type = \"project\"; // String | The resource type of favorites to be returned.\nlet workspace = \"1234\"; // String | The workspace in which to get favorites.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"name,offset,path,uri\"\n};\nusersApiInstance.getFavoritesForUser(user_gid, resource_type, workspace, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.users.getFavoritesForUser(userGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nusers_api_instance = asana.UsersApi(api_client)\nuser_gid = \"me\" # str | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\nresource_type = \"project\" # str | The resource type of favorites to be returned.\nworkspace = \"1234\" # str | The workspace in which to get favorites.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"name,offset,path,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a user's favorites\n api_response = users_api_instance.get_favorites_for_user(user_gid, resource_type, workspace, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling UsersApi->get_favorites_for_user: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.users.get_favorites_for_user(user_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "users->getFavoritesForUser($user_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.users.get_favorites_for_user(user_gid: 'user_gid', resource_type: ''resource_type_example'', workspace: ''workspace_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/teams/{team_gid}/users": { "parameters": [ { "name": "team_gid", "in": "path", "description": "Globally unique identifier for the team.", "required": true, "schema": { "type": "string" }, "example": "159874", "x-env-variable": "team" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get users in a team", "description": "Required scope: users:read\n\nReturns the compact records for all users that are members of the team.\nResults are sorted alphabetically and limited to 2000. For more results use the `/users` endpoint.", "tags": [ "Users" ], "operationId": "getUsersForTeam", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "email", "name", "photo", "photo.image_1024x1024", "photo.image_128x128", "photo.image_21x21", "photo.image_27x27", "photo.image_36x36", "photo.image_60x60", "workspaces", "workspaces.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "email", "name", "photo", "photo.image_1024x1024", "photo.image_128x128", "photo.image_21x21", "photo.image_27x27", "photo.image_36x36", "photo.image_60x60", "workspaces", "workspaces.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Returns the user records for all the members of the team, including guests and limited access users", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "users:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.users.getUsersForTeam(teamGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet usersApiInstance = new Asana.UsersApi();\nlet team_gid = \"159874\"; // String | Globally unique identifier for the team.\nlet opts = { \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,email,name,photo,photo.image_1024x1024,photo.image_128x128,photo.image_21x21,photo.image_27x27,photo.image_36x36,photo.image_60x60,workspaces,workspaces.name\"\n};\nusersApiInstance.getUsersForTeam(team_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.users.getUsersForTeam(teamGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nusers_api_instance = asana.UsersApi(api_client)\nteam_gid = \"159874\" # str | Globally unique identifier for the team.\nopts = {\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,email,name,photo,photo.image_1024x1024,photo.image_128x128,photo.image_21x21,photo.image_27x27,photo.image_36x36,photo.image_60x60,workspaces,workspaces.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get users in a team\n api_response = users_api_instance.get_users_for_team(team_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling UsersApi->get_users_for_team: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.users.get_users_for_team(team_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "users->getUsersForTeam($team_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.users.get_users_for_team(team_gid: 'team_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/users": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get users in a workspace or organization", "description": "Required scope: users:read\n\nReturns the compact records for all users in the specified workspace or organization.\nResults are sorted alphabetically and limited to 2000. For more results use the `/users` endpoint.", "tags": [ "Users" ], "operationId": "getUsersForWorkspace", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "email", "name", "photo", "photo.image_1024x1024", "photo.image_128x128", "photo.image_21x21", "photo.image_27x27", "photo.image_36x36", "photo.image_60x60", "workspaces", "workspaces.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "custom_fields", "custom_fields.date_value", "custom_fields.date_value.date", "custom_fields.date_value.date_time", "custom_fields.display_value", "custom_fields.enabled", "custom_fields.enum_options", "custom_fields.enum_options.color", "custom_fields.enum_options.enabled", "custom_fields.enum_options.name", "custom_fields.enum_value", "custom_fields.enum_value.color", "custom_fields.enum_value.enabled", "custom_fields.enum_value.name", "custom_fields.id_prefix", "custom_fields.input_restrictions", "custom_fields.is_formula_field", "custom_fields.multi_enum_values", "custom_fields.multi_enum_values.color", "custom_fields.multi_enum_values.enabled", "custom_fields.multi_enum_values.name", "custom_fields.name", "custom_fields.number_value", "custom_fields.representation_type", "custom_fields.text_value", "custom_fields.type", "email", "name", "photo", "photo.image_1024x1024", "photo.image_128x128", "photo.image_21x21", "photo.image_27x27", "photo.image_36x36", "photo.image_60x60", "workspaces", "workspaces.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Return the users in the specified workspace or org.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "users:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.users.getUsersForWorkspace(workspaceGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet usersApiInstance = new Asana.UsersApi();\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,email,name,photo,photo.image_1024x1024,photo.image_128x128,photo.image_21x21,photo.image_27x27,photo.image_36x36,photo.image_60x60,workspaces,workspaces.name\"\n};\nusersApiInstance.getUsersForWorkspace(workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.users.getUsersForWorkspace(workspaceGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nusers_api_instance = asana.UsersApi(api_client)\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"custom_fields,custom_fields.date_value,custom_fields.date_value.date,custom_fields.date_value.date_time,custom_fields.display_value,custom_fields.enabled,custom_fields.enum_options,custom_fields.enum_options.color,custom_fields.enum_options.enabled,custom_fields.enum_options.name,custom_fields.enum_value,custom_fields.enum_value.color,custom_fields.enum_value.enabled,custom_fields.enum_value.name,custom_fields.id_prefix,custom_fields.input_restrictions,custom_fields.is_formula_field,custom_fields.multi_enum_values,custom_fields.multi_enum_values.color,custom_fields.multi_enum_values.enabled,custom_fields.multi_enum_values.name,custom_fields.name,custom_fields.number_value,custom_fields.representation_type,custom_fields.text_value,custom_fields.type,email,name,photo,photo.image_1024x1024,photo.image_128x128,photo.image_21x21,photo.image_27x27,photo.image_36x36,photo.image_60x60,workspaces,workspaces.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get users in a workspace or organization\n api_response = users_api_instance.get_users_for_workspace(workspace_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling UsersApi->get_users_for_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.users.get_users_for_workspace(workspace_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "users->getUsersForWorkspace($workspace_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.users.get_users_for_workspace(workspace_gid: 'workspace_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/webhooks": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get multiple webhooks", "description": "Required scope: webhooks:read\n\nGet the compact representation of all webhooks your app has registered for the authenticated user in the given workspace.", "tags": [ "Webhooks" ], "operationId": "getWebhooks", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } }, { "name": "workspace", "in": "query", "required": true, "description": "The workspace to query for webhooks in.", "schema": { "type": "string" }, "example": "1331" }, { "name": "resource", "in": "query", "description": "Only return webhooks for the given resource.", "schema": { "type": "string" }, "example": "51648" }, { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "active", "created_at", "delivery_retry_count", "failure_deletion_timestamp", "filters", "filters.action", "filters.fields", "filters.resource_subtype", "last_failure_at", "last_failure_content", "last_success_at", "next_attempt_after", "offset", "path", "resource", "resource.name", "target", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "created_at", "delivery_retry_count", "failure_deletion_timestamp", "filters", "filters.action", "filters.fields", "filters.resource_subtype", "last_failure_at", "last_failure_content", "last_success_at", "next_attempt_after", "offset", "path", "resource", "resource.name", "target", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested webhooks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "description": "Webhook objects represent the state of an active subscription for a server to be updated with information from Asana. This schema represents the subscription itself, not the objects that are sent to the server. For information on those please refer to the [event](/reference/events) schema.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "webhook", "x-insert-after": "gid" }, "active": { "description": "If true, the webhook will send events - if false it is considered inactive and will not generate events.", "type": "boolean", "readOnly": true, "example": false }, "resource": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } }, "target": { "description": "The URL to receive the HTTP POST.", "type": "string", "format": "uri", "readOnly": true, "example": "https://example.com/receive-webhook/7654" } } }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "last_failure_at": { "description": "The timestamp when the webhook last received an error when sending an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "last_failure_content": { "description": "The contents of the last error response sent to the webhook when attempting to deliver events to the target.", "type": "string", "readOnly": true, "example": "500 Server Error\\n\\nCould not complete the request" }, "last_success_at": { "description": "The timestamp when the webhook last successfully sent an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "delivery_retry_count": { "description": "The number of times the webhook has retried delivery of events to the target (resets after a successful attempt).", "type": "integer", "readOnly": true, "example": 3 }, "next_attempt_after": { "description": "The timestamp after which the webhook will next attempt to deliver an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "failure_deletion_timestamp": { "description": "The timestamp when the webhook will be deleted if there is no successful attempt to deliver events to the target", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "filters": { "description": "Whitelist of filters to apply to events from this webhook. If a webhook event passes any of the filters the event will be delivered; otherwise no event will be sent to the receiving server.", "type": "array", "items": { "allOf": [ { "type": "object", "description": "A WebhookFilter can be passed on creation of a webhook in order to filter the types of actions that trigger delivery of an [event](/reference/events)", "properties": { "resource_type": { "type": "string", "description": "The type of the resource which created the event when modified; for example, to filter to changes on regular tasks this field should be set to `task`.", "example": "task" }, "resource_subtype": { "description": "The resource subtype of the resource that the filter applies to. This should be set to the same value as is returned on the `resource_subtype` field on the resources themselves.", "type": "string", "example": "milestone" }, "action": { "type": "string", "description": "The type of change on the **resource** to pass through the filter. For more information refer to `Event.action` in the [event](/reference/events) schema. This can be one of `changed`, `added`, `removed`, `deleted`, and `undeleted` depending on the nature of what has occurred on the resource.", "example": "changed" }, "fields": { "type": "array", "description": "*Conditional.* A whitelist of fields for events which will pass the filter when the resource is changed. These can be any combination of the fields on the resources themselves. This field is only valid for `action` of type `changed`\n*Note: Subscriptions created on higher-level resources such as a Workspace, Team, or Portfolio do not support fields.*", "items": { "type": "string" }, "example": [ "due_at", "due_on", "dependencies" ] } } }, { "description": "A set of filters to specify a whitelist for what types of events will be delivered." }, { "type": "object" } ] } } } } ] } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "webhooks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.webhooks.getWebhooks(resource, workspace)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet webhooksApiInstance = new Asana.WebhooksApi();\nlet workspace = \"1331\"; // String | The workspace to query for webhooks in.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'resource': \"51648\", \n 'opt_fields': \"active,created_at,delivery_retry_count,failure_deletion_timestamp,filters,filters.action,filters.fields,filters.resource_subtype,last_failure_at,last_failure_content,last_success_at,next_attempt_after,offset,path,resource,resource.name,target,uri\"\n};\nwebhooksApiInstance.getWebhooks(workspace, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.webhooks.getWebhooks({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nwebhooks_api_instance = asana.WebhooksApi(api_client)\nworkspace = \"1331\" # str | The workspace to query for webhooks in.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'resource': \"51648\", # str | Only return webhooks for the given resource.\n 'opt_fields': \"active,created_at,delivery_retry_count,failure_deletion_timestamp,filters,filters.action,filters.fields,filters.resource_subtype,last_failure_at,last_failure_content,last_success_at,next_attempt_after,offset,path,resource,resource.name,target,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple webhooks\n api_response = webhooks_api_instance.get_webhooks(workspace, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling WebhooksApi->get_webhooks: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.webhooks.get_webhooks({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "webhooks->getWebhooks(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.webhooks.get_webhooks(workspace: ''workspace_example'', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "post": { "summary": "Establish a webhook", "description": "Required scope: webhooks:write\n\nEstablishing a webhook is a two-part process. First, a simple HTTP POST\nrequest initiates the creation similar to creating any other resource.\n\nNext, in the middle of this request comes the confirmation handshake.\nWhen a webhook is created, we will send a test POST to the target with an\n`X-Hook-Secret` header. The target must respond with a `200 OK` or `204\nNo Content` and a matching `X-Hook-Secret` header to confirm that this\nwebhook subscription is indeed expected. We strongly recommend storing\nthis secret to be used to verify future webhook event signatures.\n\nThe POST request to create the webhook will then return with the status\nof the request. If you do not acknowledge the webhook\u2019s confirmation\nhandshake it will fail to setup, and you will receive an error in\nresponse to your attempt to create it. This means you need to be able to\nreceive and complete the webhook *while* the POST request is in-flight\n(in other words, have a server that can handle requests asynchronously).\n\nInvalid hostnames like localhost will receive a 403 Forbidden status code.\n\n```\n# Request\ncurl -H \"Authorization: Bearer \" \\\n-X POST https://app.asana.com/api/1.0/webhooks \\\n-d \"resource=8675309\" \\\n-d \"target=https://example.com/receive-webhook/7654\"\n```\n\n```\n# Handshake sent to https://example.com/\nPOST /receive-webhook/7654\nX-Hook-Secret: b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81\n```\n\n```\n# Handshake response sent by example.com\nHTTP/1.1 200\nX-Hook-Secret: b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81\n```\n\n```\n# Response\nHTTP/1.1 201\n{\n \"data\": {\n \"gid\": \"43214\",\n \"resource\": {\n \"gid\": \"8675309\",\n \"name\": \"Bugs\"\n },\n \"target\": \"https://example.com/receive-webhook/7654\",\n \"active\": false,\n \"last_success_at\": null,\n \"last_failure_at\": null,\n \"last_failure_content\": null\n },\n \"X-Hook-Secret\": \"b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81\"\n}\n```", "tags": [ "Webhooks" ], "operationId": "createWebhook", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "active", "created_at", "delivery_retry_count", "failure_deletion_timestamp", "filters", "filters.action", "filters.fields", "filters.resource_subtype", "last_failure_at", "last_failure_content", "last_success_at", "next_attempt_after", "resource", "resource.name", "target" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "created_at", "delivery_retry_count", "failure_deletion_timestamp", "filters", "filters.action", "filters.fields", "filters.resource_subtype", "last_failure_at", "last_failure_content", "last_success_at", "next_attempt_after", "resource", "resource.name", "target" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The webhook workspace and target.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "resource": { "description": "A resource ID to subscribe to. Many Asana resources are valid to create webhooks on, but higher-level resources require filters.", "type": "string", "example": "12345" }, "target": { "description": "The URL to receive the HTTP POST. The full URL will be used to deliver events from this webhook (including parameters) which allows encoding of application-specific state when the webhook is created.", "type": "string", "format": "uri", "example": "https://example.com/receive-webhook/7654?app_specific_param=app_specific_value" }, "filters": { "type": "array", "description": "An array of WebhookFilter objects to specify a whitelist of filters to apply to events from this webhook. If a webhook event passes any of the filters the event will be delivered; otherwise no event will be sent to the receiving server.", "items": { "allOf": [ { "type": "object", "description": "A WebhookFilter can be passed on creation of a webhook in order to filter the types of actions that trigger delivery of an [event](/reference/events)", "properties": { "resource_type": { "type": "string", "description": "The type of the resource which created the event when modified; for example, to filter to changes on regular tasks this field should be set to `task`.", "example": "task" }, "resource_subtype": { "description": "The resource subtype of the resource that the filter applies to. This should be set to the same value as is returned on the `resource_subtype` field on the resources themselves.", "type": "string", "example": "milestone" }, "action": { "type": "string", "description": "The type of change on the **resource** to pass through the filter. For more information refer to `Event.action` in the [event](/reference/events) schema. This can be one of `changed`, `added`, `removed`, `deleted`, and `undeleted` depending on the nature of what has occurred on the resource.", "example": "changed" }, "fields": { "type": "array", "description": "*Conditional.* A whitelist of fields for events which will pass the filter when the resource is changed. These can be any combination of the fields on the resources themselves. This field is only valid for `action` of type `changed`\n*Note: Subscriptions created on higher-level resources such as a Workspace, Team, or Portfolio do not support fields.*", "items": { "type": "string" }, "example": [ "due_at", "due_on", "dependencies" ] } } }, { "description": "A set of filters to specify a whitelist for what types of events will be delivered." }, { "type": "object" } ] } } }, "required": [ "resource", "target" ] } } } } } }, "responses": { "201": { "description": "Successfully created the requested webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "Webhook objects represent the state of an active subscription for a server to be updated with information from Asana. This schema represents the subscription itself, not the objects that are sent to the server. For information on those please refer to the [event](/reference/events) schema.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "webhook", "x-insert-after": "gid" }, "active": { "description": "If true, the webhook will send events - if false it is considered inactive and will not generate events.", "type": "boolean", "readOnly": true, "example": false }, "resource": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } }, "target": { "description": "The URL to receive the HTTP POST.", "type": "string", "format": "uri", "readOnly": true, "example": "https://example.com/receive-webhook/7654" } } }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "last_failure_at": { "description": "The timestamp when the webhook last received an error when sending an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "last_failure_content": { "description": "The contents of the last error response sent to the webhook when attempting to deliver events to the target.", "type": "string", "readOnly": true, "example": "500 Server Error\\n\\nCould not complete the request" }, "last_success_at": { "description": "The timestamp when the webhook last successfully sent an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "delivery_retry_count": { "description": "The number of times the webhook has retried delivery of events to the target (resets after a successful attempt).", "type": "integer", "readOnly": true, "example": 3 }, "next_attempt_after": { "description": "The timestamp after which the webhook will next attempt to deliver an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "failure_deletion_timestamp": { "description": "The timestamp when the webhook will be deleted if there is no successful attempt to deliver events to the target", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "filters": { "description": "Whitelist of filters to apply to events from this webhook. If a webhook event passes any of the filters the event will be delivered; otherwise no event will be sent to the receiving server.", "type": "array", "items": { "allOf": [ { "type": "object", "description": "A WebhookFilter can be passed on creation of a webhook in order to filter the types of actions that trigger delivery of an [event](/reference/events)", "properties": { "resource_type": { "type": "string", "description": "The type of the resource which created the event when modified; for example, to filter to changes on regular tasks this field should be set to `task`.", "example": "task" }, "resource_subtype": { "description": "The resource subtype of the resource that the filter applies to. This should be set to the same value as is returned on the `resource_subtype` field on the resources themselves.", "type": "string", "example": "milestone" }, "action": { "type": "string", "description": "The type of change on the **resource** to pass through the filter. For more information refer to `Event.action` in the [event](/reference/events) schema. This can be one of `changed`, `added`, `removed`, `deleted`, and `undeleted` depending on the nature of what has occurred on the resource.", "example": "changed" }, "fields": { "type": "array", "description": "*Conditional.* A whitelist of fields for events which will pass the filter when the resource is changed. These can be any combination of the fields on the resources themselves. This field is only valid for `action` of type `changed`\n*Note: Subscriptions created on higher-level resources such as a Workspace, Team, or Portfolio do not support fields.*", "items": { "type": "string" }, "example": [ "due_at", "due_on", "dependencies" ] } } }, { "description": "A set of filters to specify a whitelist for what types of events will be delivered." }, { "type": "object" } ] } } } } ] }, "X-Hook-Secret": { "type": "string", "description": "The secret to be used to verify future webhook event signatures.", "example": "b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "webhooks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nWebhook result = client.webhooks.createWebhook()\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet webhooksApiInstance = new Asana.WebhooksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The webhook workspace and target.\nlet opts = { \n 'opt_fields': \"active,created_at,delivery_retry_count,failure_deletion_timestamp,filters,filters.action,filters.fields,filters.resource_subtype,last_failure_at,last_failure_content,last_success_at,next_attempt_after,resource,resource.name,target\"\n};\nwebhooksApiInstance.createWebhook(body, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.webhooks.createWebhook({field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nwebhooks_api_instance = asana.WebhooksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The webhook workspace and target.\nopts = {\n 'opt_fields': \"active,created_at,delivery_retry_count,failure_deletion_timestamp,filters,filters.action,filters.fields,filters.resource_subtype,last_failure_at,last_failure_content,last_success_at,next_attempt_after,resource,resource.name,target\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Establish a webhook\n api_response = webhooks_api_instance.create_webhook(body, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling WebhooksApi->create_webhook: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.webhooks.create_webhook({'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "webhooks->createWebhook(array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.webhooks.create_webhook(field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 6, "x-moar-complexity-skipped": false } }, "/webhooks/{webhook_gid}": { "parameters": [ { "name": "webhook_gid", "in": "path", "description": "Globally unique identifier for the webhook.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "webhook" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a webhook", "description": "Required scope: webhooks:read\n\nReturns the full record for the given webhook.", "tags": [ "Webhooks" ], "operationId": "getWebhook", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "active", "created_at", "delivery_retry_count", "failure_deletion_timestamp", "filters", "filters.action", "filters.fields", "filters.resource_subtype", "last_failure_at", "last_failure_content", "last_success_at", "next_attempt_after", "resource", "resource.name", "target" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "created_at", "delivery_retry_count", "failure_deletion_timestamp", "filters", "filters.action", "filters.fields", "filters.resource_subtype", "last_failure_at", "last_failure_content", "last_success_at", "next_attempt_after", "resource", "resource.name", "target" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "Webhook objects represent the state of an active subscription for a server to be updated with information from Asana. This schema represents the subscription itself, not the objects that are sent to the server. For information on those please refer to the [event](/reference/events) schema.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "webhook", "x-insert-after": "gid" }, "active": { "description": "If true, the webhook will send events - if false it is considered inactive and will not generate events.", "type": "boolean", "readOnly": true, "example": false }, "resource": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } }, "target": { "description": "The URL to receive the HTTP POST.", "type": "string", "format": "uri", "readOnly": true, "example": "https://example.com/receive-webhook/7654" } } }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "last_failure_at": { "description": "The timestamp when the webhook last received an error when sending an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "last_failure_content": { "description": "The contents of the last error response sent to the webhook when attempting to deliver events to the target.", "type": "string", "readOnly": true, "example": "500 Server Error\\n\\nCould not complete the request" }, "last_success_at": { "description": "The timestamp when the webhook last successfully sent an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "delivery_retry_count": { "description": "The number of times the webhook has retried delivery of events to the target (resets after a successful attempt).", "type": "integer", "readOnly": true, "example": 3 }, "next_attempt_after": { "description": "The timestamp after which the webhook will next attempt to deliver an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "failure_deletion_timestamp": { "description": "The timestamp when the webhook will be deleted if there is no successful attempt to deliver events to the target", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "filters": { "description": "Whitelist of filters to apply to events from this webhook. If a webhook event passes any of the filters the event will be delivered; otherwise no event will be sent to the receiving server.", "type": "array", "items": { "allOf": [ { "type": "object", "description": "A WebhookFilter can be passed on creation of a webhook in order to filter the types of actions that trigger delivery of an [event](/reference/events)", "properties": { "resource_type": { "type": "string", "description": "The type of the resource which created the event when modified; for example, to filter to changes on regular tasks this field should be set to `task`.", "example": "task" }, "resource_subtype": { "description": "The resource subtype of the resource that the filter applies to. This should be set to the same value as is returned on the `resource_subtype` field on the resources themselves.", "type": "string", "example": "milestone" }, "action": { "type": "string", "description": "The type of change on the **resource** to pass through the filter. For more information refer to `Event.action` in the [event](/reference/events) schema. This can be one of `changed`, `added`, `removed`, `deleted`, and `undeleted` depending on the nature of what has occurred on the resource.", "example": "changed" }, "fields": { "type": "array", "description": "*Conditional.* A whitelist of fields for events which will pass the filter when the resource is changed. These can be any combination of the fields on the resources themselves. This field is only valid for `action` of type `changed`\n*Note: Subscriptions created on higher-level resources such as a Workspace, Team, or Portfolio do not support fields.*", "items": { "type": "string" }, "example": [ "due_at", "due_on", "dependencies" ] } } }, { "description": "A set of filters to specify a whitelist for what types of events will be delivered." }, { "type": "object" } ] } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "webhooks:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nWebhook result = client.webhooks.getWebhook(webhookGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet webhooksApiInstance = new Asana.WebhooksApi();\nlet webhook_gid = \"12345\"; // String | Globally unique identifier for the webhook.\nlet opts = { \n 'opt_fields': \"active,created_at,delivery_retry_count,failure_deletion_timestamp,filters,filters.action,filters.fields,filters.resource_subtype,last_failure_at,last_failure_content,last_success_at,next_attempt_after,resource,resource.name,target\"\n};\nwebhooksApiInstance.getWebhook(webhook_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.webhooks.getWebhook(webhookGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nwebhooks_api_instance = asana.WebhooksApi(api_client)\nwebhook_gid = \"12345\" # str | Globally unique identifier for the webhook.\nopts = {\n 'opt_fields': \"active,created_at,delivery_retry_count,failure_deletion_timestamp,filters,filters.action,filters.fields,filters.resource_subtype,last_failure_at,last_failure_content,last_success_at,next_attempt_after,resource,resource.name,target\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a webhook\n api_response = webhooks_api_instance.get_webhook(webhook_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling WebhooksApi->get_webhook: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.webhooks.get_webhook(webhook_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "webhooks->getWebhook($webhook_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.webhooks.get_webhook(webhook_gid: 'webhook_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a webhook", "description": "Required scope: webhooks:write\n\nAn existing webhook's filters can be updated by making a PUT request on the URL for that webhook. Note that the webhook's previous `filters` array will be completely overwritten by the `filters` sent in the PUT request.", "tags": [ "Webhooks" ], "operationId": "updateWebhook", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "active", "created_at", "delivery_retry_count", "failure_deletion_timestamp", "filters", "filters.action", "filters.fields", "filters.resource_subtype", "last_failure_at", "last_failure_content", "last_success_at", "next_attempt_after", "resource", "resource.name", "target" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "created_at", "delivery_retry_count", "failure_deletion_timestamp", "filters", "filters.action", "filters.fields", "filters.resource_subtype", "last_failure_at", "last_failure_content", "last_success_at", "next_attempt_after", "resource", "resource.name", "target" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The updated filters for the webhook.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "filters": { "type": "array", "description": "An array of WebhookFilter objects to specify a whitelist of filters to apply to events from this webhook. If a webhook event passes any of the filters the event will be delivered; otherwise no event will be sent to the receiving server.", "items": { "allOf": [ { "type": "object", "description": "A WebhookFilter can be passed on creation of a webhook in order to filter the types of actions that trigger delivery of an [event](/reference/events)", "properties": { "resource_type": { "type": "string", "description": "The type of the resource which created the event when modified; for example, to filter to changes on regular tasks this field should be set to `task`.", "example": "task" }, "resource_subtype": { "description": "The resource subtype of the resource that the filter applies to. This should be set to the same value as is returned on the `resource_subtype` field on the resources themselves.", "type": "string", "example": "milestone" }, "action": { "type": "string", "description": "The type of change on the **resource** to pass through the filter. For more information refer to `Event.action` in the [event](/reference/events) schema. This can be one of `changed`, `added`, `removed`, `deleted`, and `undeleted` depending on the nature of what has occurred on the resource.", "example": "changed" }, "fields": { "type": "array", "description": "*Conditional.* A whitelist of fields for events which will pass the filter when the resource is changed. These can be any combination of the fields on the resources themselves. This field is only valid for `action` of type `changed`\n*Note: Subscriptions created on higher-level resources such as a Workspace, Team, or Portfolio do not support fields.*", "items": { "type": "string" }, "example": [ "due_at", "due_on", "dependencies" ] } } }, { "description": "A set of filters to specify a whitelist for what types of events will be delivered." }, { "type": "object" } ] } } } } } } } } }, "responses": { "200": { "description": "Successfully updated the webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "Webhook objects represent the state of an active subscription for a server to be updated with information from Asana. This schema represents the subscription itself, not the objects that are sent to the server. For information on those please refer to the [event](/reference/events) schema.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "webhook", "x-insert-after": "gid" }, "active": { "description": "If true, the webhook will send events - if false it is considered inactive and will not generate events.", "type": "boolean", "readOnly": true, "example": false }, "resource": { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } }, "target": { "description": "The URL to receive the HTTP POST.", "type": "string", "format": "uri", "readOnly": true, "example": "https://example.com/receive-webhook/7654" } } }, { "type": "object", "properties": { "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "last_failure_at": { "description": "The timestamp when the webhook last received an error when sending an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "last_failure_content": { "description": "The contents of the last error response sent to the webhook when attempting to deliver events to the target.", "type": "string", "readOnly": true, "example": "500 Server Error\\n\\nCould not complete the request" }, "last_success_at": { "description": "The timestamp when the webhook last successfully sent an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "delivery_retry_count": { "description": "The number of times the webhook has retried delivery of events to the target (resets after a successful attempt).", "type": "integer", "readOnly": true, "example": 3 }, "next_attempt_after": { "description": "The timestamp after which the webhook will next attempt to deliver an event to the target.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "failure_deletion_timestamp": { "description": "The timestamp when the webhook will be deleted if there is no successful attempt to deliver events to the target", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "filters": { "description": "Whitelist of filters to apply to events from this webhook. If a webhook event passes any of the filters the event will be delivered; otherwise no event will be sent to the receiving server.", "type": "array", "items": { "allOf": [ { "type": "object", "description": "A WebhookFilter can be passed on creation of a webhook in order to filter the types of actions that trigger delivery of an [event](/reference/events)", "properties": { "resource_type": { "type": "string", "description": "The type of the resource which created the event when modified; for example, to filter to changes on regular tasks this field should be set to `task`.", "example": "task" }, "resource_subtype": { "description": "The resource subtype of the resource that the filter applies to. This should be set to the same value as is returned on the `resource_subtype` field on the resources themselves.", "type": "string", "example": "milestone" }, "action": { "type": "string", "description": "The type of change on the **resource** to pass through the filter. For more information refer to `Event.action` in the [event](/reference/events) schema. This can be one of `changed`, `added`, `removed`, `deleted`, and `undeleted` depending on the nature of what has occurred on the resource.", "example": "changed" }, "fields": { "type": "array", "description": "*Conditional.* A whitelist of fields for events which will pass the filter when the resource is changed. These can be any combination of the fields on the resources themselves. This field is only valid for `action` of type `changed`\n*Note: Subscriptions created on higher-level resources such as a Workspace, Team, or Portfolio do not support fields.*", "items": { "type": "string" }, "example": [ "due_at", "due_on", "dependencies" ] } } }, { "description": "A set of filters to specify a whitelist for what types of events will be delivered." }, { "type": "object" } ] } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "webhooks:write" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nWebhook result = client.webhooks.updateWebhook(webhookGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet webhooksApiInstance = new Asana.WebhooksApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The updated filters for the webhook.\nlet webhook_gid = \"12345\"; // String | Globally unique identifier for the webhook.\nlet opts = { \n 'opt_fields': \"active,created_at,delivery_retry_count,failure_deletion_timestamp,filters,filters.action,filters.fields,filters.resource_subtype,last_failure_at,last_failure_content,last_success_at,next_attempt_after,resource,resource.name,target\"\n};\nwebhooksApiInstance.updateWebhook(body, webhook_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.webhooks.updateWebhook(webhookGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nwebhooks_api_instance = asana.WebhooksApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The updated filters for the webhook.\nwebhook_gid = \"12345\" # str | Globally unique identifier for the webhook.\nopts = {\n 'opt_fields': \"active,created_at,delivery_retry_count,failure_deletion_timestamp,filters,filters.action,filters.fields,filters.resource_subtype,last_failure_at,last_failure_content,last_success_at,next_attempt_after,resource,resource.name,target\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a webhook\n api_response = webhooks_api_instance.update_webhook(body, webhook_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling WebhooksApi->update_webhook: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.webhooks.update_webhook(webhook_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "webhooks->updateWebhook($webhook_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.webhooks.update_webhook(webhook_gid: 'webhook_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 4, "x-moar-complexity-skipped": false }, "delete": { "summary": "Delete a webhook", "description": "Required scope: webhooks:delete\n\nThis method *permanently* removes a webhook. Note that it may be possible to receive a request that was already in flight after deleting the webhook, but no further requests will be issued.", "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "responses": { "200": { "description": "Successfully retrieved the requested webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "webhooks:delete" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.webhooks.deleteWebhook(webhookGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet webhooksApiInstance = new Asana.WebhooksApi();\nlet webhook_gid = \"12345\"; // String | Globally unique identifier for the webhook.\n\nwebhooksApiInstance.deleteWebhook(webhook_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.webhooks.deleteWebhook(webhookGid)\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nwebhooks_api_instance = asana.WebhooksApi(api_client)\nwebhook_gid = \"12345\" # str | Globally unique identifier for the webhook.\n\n\ntry:\n # Delete a webhook\n api_response = webhooks_api_instance.delete_webhook(webhook_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling WebhooksApi->delete_webhook: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.webhooks.delete_webhook(webhook_gid, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "webhooks->deleteWebhook($webhook_gid, array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.webhooks.delete_webhook(webhook_gid: 'webhook_gid', options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/workspace_memberships/{workspace_membership_gid}": { "parameters": [ { "name": "workspace_membership_gid", "in": "path", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace_membership" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a workspace membership", "description": "Returns the complete workspace record for a single workspace membership.", "tags": [ "Workspace memberships" ], "operationId": "getWorkspaceMembership", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "created_at", "is_active", "is_admin", "is_guest", "is_view_only", "user", "user.name", "user_task_list", "user_task_list.name", "user_task_list.owner", "user_task_list.workspace", "vacation_dates", "vacation_dates.end_on", "vacation_dates.start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "is_active", "is_admin", "is_guest", "is_view_only", "user", "user.name", "user_task_list", "user_task_list.name", "user_task_list.owner", "user_task_list.workspace", "vacation_dates", "vacation_dates.end_on", "vacation_dates.start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested workspace membership.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "This object determines if a user is a member of a workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace_membership", "x-insert-after": "gid" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "workspace": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } } } }, { "type": "object", "properties": { "user_task_list": { "description": "A user task list represents the tasks assigned to a particular user. It provides API access to a user\u2019s [My tasks](https://asana.com/guide/help/fundamentals/my-tasks) view in Asana.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user_task_list", "x-insert-after": "gid" }, "name": { "description": "The name of the user task list.", "type": "string", "example": "My tasks in My Workspace" }, "owner": { "description": "The owner of the user task list, i.e. the person whose My Tasks is represented by this resource.", "readOnly": true, "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } } ] }, "workspace": { "description": "The workspace in which the user task list is located.", "readOnly": true, "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } } ] } } }, "is_active": { "type": "boolean", "readOnly": true, "description": "Indicates whether the user is currently associated with the workspace. Returns `true` for users who have joined the workspace or have been invited but not yet accepted." }, "is_admin": { "type": "boolean", "readOnly": true, "description": "Reflects if this user is an admin of the workspace." }, "is_guest": { "type": "boolean", "readOnly": true, "description": "Reflects if this user is a guest of the workspace." }, "is_view_only": { "type": "boolean", "readOnly": true, "description": "Reflects if this user has view only license in the workspace." }, "vacation_dates": { "type": "object", "readOnly": true, "nullable": true, "description": "Contains keys `start_on` and `end_on` for the vacation dates for the user in this workspace. If `start_on` is null, the entire `vacation_dates` object will be null. If `end_on` is before today, the entire `vacation_dates` object will be null.", "properties": { "start_on": { "description": "The day on which the user's vacation in this workspace starts. This is a date with `YYYY-MM-DD` format.", "type": "string", "example": "2022-11-05" }, "end_on": { "description": "The day on which the user's vacation in this workspace ends, or null if there is no end date. This is a date with `YYYY-MM-DD` format.", "nullable": true, "type": "string", "example": "2022-11-07" } } }, "created_at": { "description": "The time at which this resource was created.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.workspacememberships.getWorkspaceMembership(workspaceMembershipGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet workspaceMembershipsApiInstance = new Asana.WorkspaceMembershipsApi();\nlet workspace_membership_gid = \"12345\"; // String | \nlet opts = { \n 'opt_fields': \"created_at,is_active,is_admin,is_guest,is_view_only,user,user.name,user_task_list,user_task_list.name,user_task_list.owner,user_task_list.workspace,vacation_dates,vacation_dates.end_on,vacation_dates.start_on,workspace,workspace.name\"\n};\nworkspaceMembershipsApiInstance.getWorkspaceMembership(workspace_membership_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.workspacememberships.getWorkspaceMembership(workspaceMembershipGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nworkspace_memberships_api_instance = asana.WorkspaceMembershipsApi(api_client)\nworkspace_membership_gid = \"12345\" # str | \nopts = {\n 'opt_fields': \"created_at,is_active,is_admin,is_guest,is_view_only,user,user.name,user_task_list,user_task_list.name,user_task_list.owner,user_task_list.workspace,vacation_dates,vacation_dates.end_on,vacation_dates.start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a workspace membership\n api_response = workspace_memberships_api_instance.get_workspace_membership(workspace_membership_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling WorkspaceMembershipsApi->get_workspace_membership: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.workspace_memberships.get_workspace_membership(workspace_membership_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "workspacememberships->getWorkspaceMembership($workspace_membership_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.workspace_memberships.get_workspace_membership(workspace_membership_gid: 'workspace_membership_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/users/{user_gid}/workspace_memberships": { "parameters": [ { "name": "user_gid", "in": "path", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "required": true, "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get workspace memberships for a user", "description": "Returns the compact workspace membership records for the user.", "tags": [ "Workspace memberships" ], "operationId": "getWorkspaceMembershipsForUser", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "created_at", "is_active", "is_admin", "is_guest", "is_view_only", "offset", "path", "uri", "user", "user.name", "user_task_list", "user_task_list.name", "user_task_list.owner", "user_task_list.workspace", "vacation_dates", "vacation_dates.end_on", "vacation_dates.start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "is_active", "is_admin", "is_guest", "is_view_only", "offset", "path", "uri", "user", "user.name", "user_task_list", "user_task_list.name", "user_task_list.owner", "user_task_list.workspace", "vacation_dates", "vacation_dates.end_on", "vacation_dates.start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested user's workspace memberships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "This object determines if a user is a member of a workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace_membership", "x-insert-after": "gid" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "workspace": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.workspacememberships.getWorkspaceMembershipsForUser(userGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet workspaceMembershipsApiInstance = new Asana.WorkspaceMembershipsApi();\nlet user_gid = \"me\"; // String | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"created_at,is_active,is_admin,is_guest,is_view_only,offset,path,uri,user,user.name,user_task_list,user_task_list.name,user_task_list.owner,user_task_list.workspace,vacation_dates,vacation_dates.end_on,vacation_dates.start_on,workspace,workspace.name\"\n};\nworkspaceMembershipsApiInstance.getWorkspaceMembershipsForUser(user_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.workspacememberships.getWorkspaceMembershipsForUser(userGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nworkspace_memberships_api_instance = asana.WorkspaceMembershipsApi(api_client)\nuser_gid = \"me\" # str | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"created_at,is_active,is_admin,is_guest,is_view_only,offset,path,uri,user,user.name,user_task_list,user_task_list.name,user_task_list.owner,user_task_list.workspace,vacation_dates,vacation_dates.end_on,vacation_dates.start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get workspace memberships for a user\n api_response = workspace_memberships_api_instance.get_workspace_memberships_for_user(user_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling WorkspaceMembershipsApi->get_workspace_memberships_for_user: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.workspace_memberships.get_workspace_memberships_for_user(user_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "workspacememberships->getWorkspaceMembershipsForUser($user_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.workspace_memberships.get_workspace_memberships_for_user(user_gid: 'user_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/workspace_memberships": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "user", "in": "query", "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "schema": { "type": "string" }, "x-env-variable": "user", "example": "me" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get the workspace memberships for a workspace", "description": "Returns the compact workspace membership records for the workspace.", "tags": [ "Workspace memberships" ], "operationId": "getWorkspaceMembershipsForWorkspace", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "created_at", "is_active", "is_admin", "is_guest", "is_view_only", "offset", "path", "uri", "user", "user.name", "user_task_list", "user_task_list.name", "user_task_list.owner", "user_task_list.workspace", "vacation_dates", "vacation_dates.end_on", "vacation_dates.start_on", "workspace", "workspace.name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "is_active", "is_admin", "is_guest", "is_view_only", "offset", "path", "uri", "user", "user.name", "user_task_list", "user_task_list.name", "user_task_list.owner", "user_task_list.workspace", "vacation_dates", "vacation_dates.end_on", "vacation_dates.start_on", "workspace", "workspace.name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successfully retrieved the requested workspace's memberships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "This object determines if a user is a member of a workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace_membership", "x-insert-after": "gid" }, "user": { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, "workspace": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.workspacememberships.getWorkspaceMembershipsForWorkspace(workspaceGid, user)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet workspaceMembershipsApiInstance = new Asana.WorkspaceMembershipsApi();\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'user': \"me\", \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"created_at,is_active,is_admin,is_guest,is_view_only,offset,path,uri,user,user.name,user_task_list,user_task_list.name,user_task_list.owner,user_task_list.workspace,vacation_dates,vacation_dates.end_on,vacation_dates.start_on,workspace,workspace.name\"\n};\nworkspaceMembershipsApiInstance.getWorkspaceMembershipsForWorkspace(workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.workspacememberships.getWorkspaceMembershipsForWorkspace(workspaceGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nworkspace_memberships_api_instance = asana.WorkspaceMembershipsApi(api_client)\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'user': \"me\", # str | A string identifying a user. This can either be the string \\\"me\\\", an email, or the gid of a user.\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"created_at,is_active,is_admin,is_guest,is_view_only,offset,path,uri,user,user.name,user_task_list,user_task_list.name,user_task_list.owner,user_task_list.workspace,vacation_dates,vacation_dates.end_on,vacation_dates.start_on,workspace,workspace.name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get the workspace memberships for a workspace\n api_response = workspace_memberships_api_instance.get_workspace_memberships_for_workspace(workspace_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling WorkspaceMembershipsApi->get_workspace_memberships_for_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.workspace_memberships.get_workspace_memberships_for_workspace(workspace_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "workspacememberships->getWorkspaceMembershipsForWorkspace($workspace_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.workspace_memberships.get_workspace_memberships_for_workspace(workspace_gid: 'workspace_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/workspaces": { "parameters": [ { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "limit", "in": "query", "description": "Results per page.\nThe number of objects to return per page. The value must be between 1 and 100.", "example": 50, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset token.\nAn offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results.\n*Note: You can only pass in an offset that was returned to you via a previously paginated request.*", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", "schema": { "type": "string" } } ], "get": { "summary": "Get multiple workspaces", "description": "Required scope: workspaces:read\n\nReturns the compact records for all workspaces visible to the authorized user.", "tags": [ "Workspaces" ], "operationId": "getWorkspaces", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "email_domains", "is_organization", "name", "offset", "path", "uri" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "email_domains", "is_organization", "name", "offset", "path", "uri" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Return all workspaces visible to the authorized user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } } }, "next_page": { "type": "object", "nullable": true, "description": "*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.", "properties": { "offset": { "type": "string", "readOnly": true, "description": "Pagination offset for the request.", "example": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "path": { "type": "string", "readOnly": true, "description": "A relative path containing the query parameters to fetch for next_page", "example": "/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" }, "uri": { "type": "string", "format": "uri", "readOnly": true, "description": "A full uri containing the query parameters to fetch for next_page", "example": "https://app.asana.com/api/1.0/tasks/12345/attachments?limit=2&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "workspaces:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nList result = client.workspaces.getWorkspaces()\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet workspacesApiInstance = new Asana.WorkspacesApi();\nlet opts = { \n 'limit': 50, \n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", \n 'opt_fields': \"email_domains,is_organization,name,offset,path,uri\"\n};\nworkspacesApiInstance.getWorkspaces(opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.workspaces.getWorkspaces({param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nworkspaces_api_instance = asana.WorkspacesApi(api_client)\nopts = {\n 'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.\n 'offset': \"eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9\", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*\n 'opt_fields': \"email_domains,is_organization,name,offset,path,uri\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get multiple workspaces\n api_response = workspaces_api_instance.get_workspaces(opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling WorkspacesApi->get_workspaces: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.workspaces.get_workspaces({'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "workspaces->getWorkspaces(array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.workspaces.get_workspaces(param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "get": { "summary": "Get a workspace", "description": "Required scope: workspaces:read\n\nReturns the full workspace record for a single workspace.", "tags": [ "Workspaces" ], "operationId": "getWorkspace", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "email_domains", "is_organization", "name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "email_domains", "is_organization", "name" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Return the full workspace record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "properties": { "email_domains": { "description": "The email domains that are associated with this workspace.", "type": "array", "items": { "type": "string", "format": "uri" }, "example": [ "asana.com" ] }, "is_organization": { "description": "Whether the workspace is an *organization*.", "type": "boolean", "example": false } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "oauth2": [ "workspaces:read" ] } ], "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nWorkspace result = client.workspaces.getWorkspace(workspaceGid)\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet workspacesApiInstance = new Asana.WorkspacesApi();\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'opt_fields': \"email_domains,is_organization,name\"\n};\nworkspacesApiInstance.getWorkspace(workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.workspaces.getWorkspace(workspaceGid, {param: \"value\", param: \"value\", opt_pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nworkspaces_api_instance = asana.WorkspacesApi(api_client)\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'opt_fields': \"email_domains,is_organization,name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Get a workspace\n api_response = workspaces_api_instance.get_workspace(workspace_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling WorkspacesApi->get_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.workspaces.get_workspace(workspace_gid, {'param': 'value', 'param': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "workspaces->getWorkspace($workspace_gid, array('param' => 'value', 'param' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.workspaces.get_workspace(workspace_gid: 'workspace_gid', param: \"value\", param: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false }, "put": { "summary": "Update a workspace", "description": "A specific, existing workspace can be updated by making a PUT request on the URL for that workspace. Only the fields provided in the data block will be updated; any unspecified fields will remain unchanged.\nCurrently the only field that can be modified for a workspace is its name.\nReturns the complete, updated workspace record.", "tags": [ "Workspaces" ], "operationId": "updateWorkspace", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "email_domains", "is_organization", "name" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "email_domains", "is_organization", "name" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The workspace object with all updated properties.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } } } } } } }, "responses": { "200": { "description": "Update for the workspace was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A *workspace* is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "workspace", "x-insert-after": "gid" }, "name": { "description": "The name of the workspace.", "type": "string", "example": "My Company Workspace" } } }, { "type": "object", "properties": { "email_domains": { "description": "The email domains that are associated with this workspace.", "type": "array", "items": { "type": "string", "format": "uri" }, "example": [ "asana.com" ] }, "is_organization": { "description": "Whether the workspace is an *organization*.", "type": "boolean", "example": false } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nWorkspace result = client.workspaces.updateWorkspace(workspaceGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet workspacesApiInstance = new Asana.WorkspacesApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The workspace object with all updated properties.\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'opt_fields': \"email_domains,is_organization,name\"\n};\nworkspacesApiInstance.updateWorkspace(body, workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.workspaces.updateWorkspace(workspaceGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nworkspaces_api_instance = asana.WorkspacesApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The workspace object with all updated properties.\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'opt_fields': \"email_domains,is_organization,name\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Update a workspace\n api_response = workspaces_api_instance.update_workspace(body, workspace_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling WorkspacesApi->update_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.workspaces.update_workspace(workspace_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "workspaces->updateWorkspace($workspace_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.workspaces.update_workspace(workspace_gid: 'workspace_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 3, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/addUser": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Add a user to a workspace or organization", "description": "Add a user to a workspace or organization.\nThe user can be referenced by their globally unique user ID or their email address. Returns the full user record for the invited user.", "tags": [ "Workspaces" ], "operationId": "addUserForWorkspace", "parameters": [ { "name": "opt_fields", "in": "query", "description": "This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.", "required": false, "example": [ "email", "name", "photo", "photo.image_1024x1024", "photo.image_128x128", "photo.image_21x21", "photo.image_27x27", "photo.image_36x36", "photo.image_60x60" ], "schema": { "type": "array", "items": { "type": "string", "enum": [ "email", "name", "photo", "photo.image_1024x1024", "photo.image_128x128", "photo.image_21x21", "photo.image_27x27", "photo.image_36x36", "photo.image_60x60" ] } }, "style": "form", "explode": false } ], "requestBody": { "description": "The user to add to the workspace.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "A user identification object for specification with the addUser/removeUser endpoints.", "properties": { "user": { "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "12345" } } } } } } } }, "responses": { "200": { "description": "The user was added successfully to the workspace or organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "type": "object", "properties": { "email": { "type": "string", "format": "email", "readOnly": true, "description": "The user's email address.", "example": "gsanchez@example.com" }, "photo": { "type": "object", "nullable": true, "properties": { "image_21x21": { "type": "string", "format": "uri", "description": "PNG image of the user at 21x21 pixels." }, "image_27x27": { "type": "string", "format": "uri", "description": "PNG image of the user at 27x27 pixels." }, "image_36x36": { "type": "string", "format": "uri", "description": "PNG image of the user at 36x36 pixels." }, "image_60x60": { "type": "string", "format": "uri", "description": "PNG image of the user at 60x60 pixels." }, "image_128x128": { "type": "string", "format": "uri", "description": "PNG image of the user at 128x128 pixels." }, "image_1024x1024": { "type": "string", "format": "uri", "description": "JPEG image of the user at 1024x1024 pixels." } }, "readOnly": true, "description": "A map of the user's profile photo in various sizes, or null if no photo is set. Sizes provided are 21, 27, 36, 60, 128, and 1024. All images are in PNG format, except for 1024 (which is in JPEG format).", "example": { "image_21x21": "https://...", "image_27x27": "https://...", "image_36x36": "https://...", "image_60x60": "https://...", "image_128x128": "https://...", "image_1024x1024": "https://..." } } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.workspaces.addUserForWorkspace(workspaceGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet workspacesApiInstance = new Asana.WorkspacesApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The user to add to the workspace.\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'opt_fields': \"email,name,photo,photo.image_1024x1024,photo.image_128x128,photo.image_21x21,photo.image_27x27,photo.image_36x36,photo.image_60x60\"\n};\nworkspacesApiInstance.addUserForWorkspace(body, workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.workspaces.addUserForWorkspace(workspaceGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nworkspaces_api_instance = asana.WorkspacesApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The user to add to the workspace.\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'opt_fields': \"email,name,photo,photo.image_1024x1024,photo.image_128x128,photo.image_21x21,photo.image_27x27,photo.image_36x36,photo.image_60x60\", # list[str] | This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include.\n}\n\ntry:\n # Add a user to a workspace or organization\n api_response = workspaces_api_instance.add_user_for_workspace(body, workspace_gid, opts)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling WorkspacesApi->add_user_for_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.workspaces.add_user_for_workspace(workspace_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "workspaces->addUserForWorkspace($workspace_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.workspaces.add_user_for_workspace(workspace_gid: 'workspace_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/removeUser": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true } ], "post": { "summary": "Remove a user from a workspace or organization", "description": "Remove a user from a workspace or organization.\n\nThe user making this call must be an admin in the workspace. The user can\nbe referenced by their globally unique user ID or their email address.\n\nWhen invoked using a **Service Account Token (SAT)**, this endpoint follows the same behavior as the\n[SCIM API Delete endpoint](/docs/scim).\nTo learn more about how Asana handles user deprovisioning, refer to our\n[Help Center article on deprovisioning users](https://help.asana.com/s/article/user-deprovisioning).\n\nWhen invoked using a **Personal Access Token (PAT)**, the endpoint behaves similarly, except that\nownership of the user\u2019s resources is transferred to the **PAT owner** instead of the admin\n[specified in the Admin Console](https://help.asana.com/s/article/user-deprovisioning#gl-deprovisioning).\n\n**Note:** If you wish to retain access to a user\u2019s private resources\n(i.e., those visible only to that user), you have to make them public manually\n(or ask the user to do so) before removal.\n\nReturns an empty data record.", "tags": [ "Workspaces" ], "operationId": "removeUserForWorkspace", "requestBody": { "description": "The user to remove from the workspace.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "A user identification object for specification with the addUser/removeUser endpoints.", "properties": { "user": { "description": "A string identifying a user. This can either be the string \"me\", an email, or the gid of a user.", "type": "string", "example": "12345" } } } } } } } }, "responses": { "200": { "description": "The user was removed successfully to the workspace or organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An empty object. Some endpoints do not return an object on success. The success is conveyed through a 2-- status code and returning an empty object." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "java", "install": "com.asanaasana1.0.0", "code": "import com.asana.Client;\n\nClient client = Client.accessToken(\"PERSONAL_ACCESS_TOKEN\");\n\nJsonElement result = client.workspaces.removeUserForWorkspace(workspaceGid)\n .data(\"field\", \"value\")\n .data(\"field\", \"value\")\n .option(\"pretty\", true)\n .execute();" }, { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet workspacesApiInstance = new Asana.WorkspacesApi();\nlet body = {\"data\": {\"\": \"\", \"\": \"\",}}; // Object | The user to remove from the workspace.\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\n\nworkspacesApiInstance.removeUserForWorkspace(body, workspace_gid).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "node", "install": "npm install asana@1.0.5", "code": "const asana = require('asana');\n\nconst client = asana.Client.create().useAccessToken('PERSONAL_ACCESS_TOKEN');\n\nclient.workspaces.removeUserForWorkspace(workspaceGid, {field: \"value\", field: \"value\", pretty: true})\n .then((result) => {\n console.log(result);\n });", "name": "node-sdk-v1" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nworkspaces_api_instance = asana.WorkspacesApi(api_client)\nbody = {\"data\": {\"\": \"\", \"\": \"\",}} # dict | The user to remove from the workspace.\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\n\n\ntry:\n # Remove a user from a workspace or organization\n api_response = workspaces_api_instance.remove_user_for_workspace(body, workspace_gid)\n pprint(api_response)\nexcept ApiException as e:\n print(\"Exception when calling WorkspacesApi->remove_user_for_workspace: %s\\n\" % e)", "name": "python-sdk-v5" }, { "language": "python", "install": "pip install asana==3.2.3", "code": "import asana\n\nclient = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')\n\nresult = client.workspaces.remove_user_for_workspace(workspace_gid, {'field': 'value', 'field': 'value'}, opt_pretty=True)", "name": "python-sdk-v3" }, { "language": "php", "install": "composer require asana/asana", "code": "workspaces->removeUserForWorkspace($workspace_gid, array('field' => 'value', 'field' => 'value'), array('opt_pretty' => 'true'))" }, { "language": "ruby", "install": "gem install asana", "code": "require 'asana'\n\nclient = Asana::Client.new do |c|\n c.authentication :access_token, 'PERSONAL_ACCESS_TOKEN'\nend\n\nresult = client.workspaces.remove_user_for_workspace(workspace_gid: 'workspace_gid', field: \"value\", field: \"value\", options: {pretty: true})" } ] }, "x-moar-primitive-count": 1, "x-moar-complexity-skipped": false } }, "/workspaces/{workspace_gid}/events": { "parameters": [ { "name": "workspace_gid", "in": "path", "description": "Globally unique identifier for the workspace or organization.", "required": true, "schema": { "type": "string" }, "example": "12345", "x-env-variable": "workspace" }, { "name": "opt_pretty", "in": "query", "description": "Provides \u201cpretty\u201d output.\nProvides the response in a \u201cpretty\u201d format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean" }, "style": "form", "example": true }, { "name": "sync", "in": "query", "required": false, "description": "A sync token received from the last request, or none on first sync. Events will be returned from the point in time that the sync token was generated.\n*Note: On your first request, omit the sync token. The response will be the same as for an expired sync token, and will include a new valid sync token. If the sync token is too old (which may happen from time to time) the API will return a `412 Precondition Failed` error, and include a fresh sync token in the response.*", "schema": { "type": "string" }, "example": "de4774f6915eae04714ca93bb2f5ee81" } ], "get": { "summary": "Get workspace events", "description": "Returns the full record for all events that have occurred since the sync token was created.\nThe response is a list of events and the schema of each event is as described [here](/reference/events).\nAsana limits a single sync token to 1000 events. If more than 1000 events exist for a given domain, `has_more: true` will be returned in the response, indicating that there are more events to pull.", "tags": [ "Workspaces" ], "operationId": "getWorkspaceEvents", "responses": { "200": { "description": "Successfully retrieved events.", "content": { "application/json": { "schema": { "type": "object", "description": "The full record for all events that have occurred since the sync token was created.", "properties": { "data": { "type": "array", "items": { "description": "An *event* is an object representing a change to a resource that was\nobserved by an event subscription or delivered asynchronously to\nthe target location of an active webhook.\n\nThe event may be triggered by a different `user` than the\nsubscriber. For example, if user A subscribes to a task and user B\nmodified it, the event's user will be user B. Note: Some events\nare generated by the system, and will have `null` as the user. API\nconsumers should make sure to handle this case.\n\nThe `resource` that triggered the event may be different from the one\nthat the events were requested for or the webhook is subscribed to. For\nexample, a subscription to a project will contain events for tasks\ncontained within the project.\n\n**Note:** pay close attention to the relationship between the fields\n`Event.action` and `Event.change.action`.\n`Event.action` represents the action taken on the resource\nitself, and `Event.change.action` represents how the information\nwithin the resource's fields have been modified.\n\nFor instance, consider these scenarios:\n\n\n* When at task is added to a project, `Event.action` will be\n`added`, `Event.parent` will be an object with the `id` and\n`type` of the project, and there will be no `change` field.\n\n\n* When an assignee is set on the task, `Event.parent` will be\n`null`, `Event.action` will be `changed`,\n`Event.change.action` will be `changed`, and `new_value` will\nbe an object with the user's `id` and `type`.\n\n\n* When a collaborator is added to the task, `Event.parent` will\nbe `null`, `Event.action` will be `changed`,\n`Event.change.action` will be `added`, and `added_value` will be\nan object with the user's `id` and `type`.", "type": "object", "properties": { "user": { "allOf": [ { "description": "A *user* object represents an account in Asana that can be given access to various workspaces, projects, and tasks.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "user", "x-insert-after": "gid" }, "name": { "type": "string", "description": "*Read-only except when same user as requester*. The user's name.", "example": "Greg Sanchez" } } }, { "description": "The user who triggered the event." } ] }, "resource": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } }, { "description": "The resource which has triggered the event by being modified in some way." } ] }, "type": { "description": "*Deprecated: Refer to the resource_type of the resource.* The type of the resource that generated the event.", "type": "string", "readOnly": true, "example": "task" }, "action": { "description": "The type of action taken on the **resource** that triggered the event. This can be one of `changed`, `added`, `removed`, `deleted`, or `undeleted` depending on the nature of the event.", "type": "string", "readOnly": true, "example": "changed" }, "parent": { "allOf": [ { "description": "A generic Asana Resource, containing a globally unique identifier.", "type": "object", "properties": { "gid": { "description": "Globally unique identifier of the resource, as a string.", "type": "string", "readOnly": true, "example": "12345", "x-insert-after": false }, "resource_type": { "description": "The base type of this resource.", "type": "string", "readOnly": true, "example": "task", "x-insert-after": "gid" }, "name": { "description": "The name of the object.", "type": "string", "example": "Bug Task" } } }, { "description": "For added/removed events, the parent object that resource was added to or removed from. The parent will be `null` for other event types." } ] }, "created_at": { "description": "The timestamp when the event occurred.", "type": "string", "format": "date-time", "readOnly": true, "example": "2012-02-22T02:06:58.147Z" }, "change": { "type": "object", "description": "Information about the type of change that has occurred. This field is only present when the value of the property `action`, describing the action taken on the **resource**, is `changed`.", "readOnly": true, "properties": { "field": { "description": "The name of the field that has changed in the resource.", "type": "string", "readOnly": true, "example": "assignee" }, "action": { "description": "The type of action taken on the **field** which has been changed. This can be one of `changed`, `added`, or `removed` depending on the nature of the change.", "type": "string", "readOnly": true, "example": "changed" }, "new_value": { "description": "*Conditional.* This property is only present when the value of the event's `change.action` is `changed` _and_ the `new_value` is an Asana resource. This will be only the `gid` and `resource_type` of the resource when the events come from webhooks; this will be the compact representation (and can have fields expanded with [opt_fields](/docs/inputoutput-options)) when using the [get events](/reference/getevents) endpoint.", "example": { "gid": "12345", "resource_type": "user" } }, "added_value": { "description": "*Conditional.* This property is only present when the value of the event's `change.action` is `added` _and_ the `added_value` is an Asana resource. This will be only the `gid` and `resource_type` of the resource when the events come from webhooks; this will be the compact representation (and can have fields expanded with [opt_fields](/docs/inputoutput-options)) when using the [get events](/reference/getevents) endpoint.", "example": { "gid": "12345", "resource_type": "user" } }, "removed_value": { "description": "*Conditional.* This property is only present when the value of the event's `change.action` is `removed` _and_ the `removed_value` is an Asana resource. This will be only the `gid` and `resource_type` of the resource when the events come from webhooks; this will be the compact representation (and can have fields expanded with [opt_fields](/docs/inputoutput-options)) when using the [get events](/reference/getevents) endpoint.", "example": { "gid": "12345", "resource_type": "user" } } } } } } }, "sync": { "description": "A sync token to be used with the next call to the /events endpoint.", "type": "string", "example": "de4774f6915eae04714ca93bb2f5ee81" }, "has_more": { "description": "Indicates whether there are more events to pull.", "type": "boolean", "example": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-readme": { "code-samples": [ { "language": "node", "install": "npm install asana", "code": "const Asana = require('asana');\n\nlet client = Asana.ApiClient.instance;\nlet token = client.authentications['token'];\ntoken.accessToken = '';\n\nlet workspacesApiInstance = new Asana.WorkspacesApi();\nlet workspace_gid = \"12345\"; // String | Globally unique identifier for the workspace or organization.\nlet opts = { \n 'sync': \"de4774f6915eae04714ca93bb2f5ee81\"\n};\nworkspacesApiInstance.getWorkspaceEvents(workspace_gid, opts).then((result) => {\n console.log('API called successfully. Returned data: ' + JSON.stringify(result.data, null, 2));\n}, (error) => {\n console.error(error.response.body);\n});", "name": "node-sdk-v3" }, { "language": "python", "install": "pip install asana", "code": "import asana\nfrom asana.rest import ApiException\nfrom pprint import pprint\n\nconfiguration = asana.Configuration()\nconfiguration.access_token = ''\napi_client = asana.ApiClient(configuration)\n\n# create an instance of the API class\nworkspaces_api_instance = asana.WorkspacesApi(api_client)\nworkspace_gid = \"12345\" # str | Globally unique identifier for the workspace or organization.\nopts = {\n 'sync': \"de4774f6915eae04714ca93bb2f5ee81\", # str | A sync token received from the last request, or none on first sync. Events will be returned from the point in time that the sync token was generated. *Note: On your first request, omit the sync token. The response will be the same as for an expired sync token, and will include a new valid sync token. If the sync token is too old (which may happen from time to time) the API will return a `412 Precondition Failed` error, and include a fresh sync token in the response.*\n}\n\ntry:\n # Get workspace events\n api_response = workspaces_api_instance.get_workspace_events(workspace_gid, opts)\n for data in api_response:\n pprint(data)\nexcept ApiException as e:\n print(\"Exception when calling WorkspacesApi->get_workspace_events: %s\\n\" % e)", "name": "python-sdk-v5" } ] }, "x-moar-primitive-count": 0, "x-moar-complexity-skipped": false } } } }