This repository has been archived by the owner on Sep 11, 2024. It is now read-only.
forked from ringcentral/slate
-
Notifications
You must be signed in to change notification settings - Fork 28
/
Copy pathasana_oas.yaml
13900 lines (13460 loc) · 478 KB
/
asana_oas.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
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/developer-docs/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/developer-docs/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
- CustomFieldResponse
- CustomFieldCompact
- EnumOption
- EventResponse
- ErrorResponse
- GoalResponse
- GoalCompact
- GoalMembershipCompact
- GoalMembershipBase
- GoalMembershipResponse
- GoalRelationshipResponse
- GoalRelationshipCompact
- JobResponse
- JobCompact
- OrganizationExportResponse
- OrganizationExportCompact
- PortfolioMembershipResponse
- PortfolioMembershipCompact
- PortfolioResponse
- PortfolioCompact
- ProjectBriefResponse
- ProjectBriefCompact
- ProjectMembershipResponse
- ProjectMembershipCompact
- ProjectResponse
- ProjectCompact
- ProjectStatusResponse
- ProjectStatusCompact
- ProjectTemplateCompact
- ProjectTemplateResponse
- 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: 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/supported-auditlogevents)
in your organization's Asana instance.
The audit log API allows you to monitor and act upon important security
and compliance-related changes. Organizations might use this API endpoint to:
* Set up proactive alerting with a Security Information and Event Management
(SIEM) tool like [Splunk](https://asana.com/guide/help/api/splunk)
* Conduct reactive investigations when a security incident takes place
* Visualize key domain data in aggregate to identify security trends
Note that since the API provides insight into what is happening in an Asana
instance, the data is [read-only](/docs/get-audit-log-events). That is, there
are no "write" or "update" endpoints for audit log events.
Only [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.
For a full list of
supported events, see [supported AuditLogEvents](/docs/supported-auditlogevents).
- 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:
* Modern browsers limit the number of requests that a single web page can
make at once.
* Mobile apps will use more battery life to keep the cellular radio on
when making a series of requests.
* There is an overhead cost to developing software that can make multiple
requests in parallel.
* Some cloud platforms handle parallelism poorly, or disallow it
entirely.
To make development easier in these use cases, Asana provides a **batch
API** that enables developers to perform multiple “actions” by making
only a single HTTP request.
#### Making a batch request
To 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
“action” objects. Each action represents a standard request to an
existing endpoint in the Asana API.
**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`.
When 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).
The 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)
The 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.
#### Rate limiting
The 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.
If 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.
#### Restrictions
Not 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:
* Uploading attachments
* Creating, getting, or deleting organization exports
* Any SCIM operations
* 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._
In 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.
`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.
#### Characteristics of custom fields
* 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.
* 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.
* 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.
* Tasks have custom field _values_ assigned to them.
#### Types of custom fields
Integrations using custom fields need to be aware of the six basic types that
a custom field can adopt. These types are:
* `text` - an arbitrary, relatively short string of text
* `number` - a number with a defined level of precision
* `enum` - a selection of a single option from a defined list of options (i.e.,
mutually exclusive selections)
* `multi_enum` - a selection of one or more options from a defined list of options
(i.e., mutually inclusive selections)
* `date` - a reference date with an optional time value
* `people` - a list of active contributors (i.e., where their relationship to
the work is defined in the custom field title)
#### Example use case
Consider 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.
A 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".
A 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`.
#### Custom fields in the API
These 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.
Text fields are currently limited to 1024 characters. On tasks, their
custom field value will have a `text_value` property to represent this
field.
Number 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.
#### Enum fields
Enum 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:
* `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`.
* `name` - the name of the option (e.g., "Choice #1")
* `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.
* `color` - a color associated with this choice.
On 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.
#### Querying an organization for its custom fields
For custom fields shared across the workspace or organization, the
workspace [can be queried](/docs/get-a-workspaces-custom-fields)
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`.
#### Accessing custom field definitions
The [custom fields](/docs/get-a-custom-field) 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.
#### Associating custom fields with a project or portfolio
A mapping between a custom field and a project or portfolio is handled with
a
[custom field settings](/docs/asana-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).
#### Accessing custom field values on tasks or projects
The [tasks](/docs/get-a-task) 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.
Of 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.
Custom 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](/docs/update-a-task) endpoint.
Custom fields on projects follow this same pattern.
#### Warning: Program defensively with regards to custom field definitions
Asana 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.
Storing 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.
#### Enabled and disabled values
When 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.
_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._
Moving 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.
In 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.
Note 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.
#### Custom field access control
Custom 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: 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.
In 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).
Establish 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.
Subsequent requests should always provide the sync token from the
immediately preceding call.
Sync 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.
When 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.
Sync tokens always expire after 24 hours, but may expire sooner,
depending on load on the service.
- 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, 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.
Only the creator of the duplication process can access the duplication
status of the new object.
*Note*: With any work that is handled asynchronously
(e.g., [project instantation from a template](/docs/instantiate-a-project-from-a-project-template),
duplicating a [task](/docs/duplicate-a-task) or [project](/docs/duplicate-a-project),
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: Organization exports
description: >-
An `organization_export` object represents a request to export the
complete data of an organization in JSON format.
To export an organization using this API:
* Create an `organization_export`
[request](/docs/create-an-organization-export-request)
and store the ID that is returned.
* Request the `organization_export` every few minutes, until the
`state` field contains ‘finished’.
* 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
for large organizations.
*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](/docs/asana-statuses).
Portfolios have some restrictions on size. Each portfolio has a max of 500
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.
Projects 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.
Followers 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.
**Note:** You can use certain project endpoints to operate on
[user task lists](/docs/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](/docs/user-task-lists)
by using the following
projects endpoints: [Add a custom field to a project](/docs/add-a-custom-field-to-a-project),
[Remove a custom field from a project](/docs/remove-a-custom-field-from-a-project)
and
[Get a project's custom fields](/docs/get-a-projects-custom-fields)
- name: Project briefs
description: >-
A project brief object represents a rich text document that describes
a project.
Please 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 “comment-only” projects in Asana, a user’s
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](/docs/asana-statuses)*
A 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, "red" for projects that
are behind, and "blue" for projects on hold.
Project 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
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.
Project templates in organizations are shared with a single team. Currently, the
team of a project template cannot be changed via the API.
- 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.
Sections are largely a shared idiom in Asana’s API for both list and
board views of a project regardless of the project’s layout.
The ‘memberships’ property when
[getting a task](/docs/get-a-task)
will return the information for the section or the column under
‘section’ in the response.
- name: Status updates
description: |-
A status update is an update on the progress of a particular object,
and is sent out to all followers when created. These updates
include both text describing the update and a `status_type` intended to
represent the overall state of the project. These include: `on_track` for projects that
are on track, `at_risk` for projects at risk, `off_track` for projects that
are behind, and `on_hold` for projects on hold.
Status 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.*
A 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.
Tags 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.
Sections 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.
[Queries](/docs/get-multiple-tasks)
return a [compact representation of each task object](/docs/task-compact). To
retrieve *all* fields or *specific set* of the fields, use
[field selectors](/docs/input-output-options) to manipulate what data is included
in a response.
- 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](/docs/goals).
- 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.
Like 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.).
For a more detailed explanation of webhooks see the [overview of webhooks](/docs/overview-of-webhooks).
- name: Workspaces
description: >-
A *workspace* is the highest-level organizational unit in Asana. All
projects and tasks have an associated workspace.
An *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.
Over 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.
Some 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.
The 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 “pretty” output.
Provides the response in a “pretty” 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.
The number of objects to return per page. The value must be between 1
and 100.
example: 50
schema:
type: integer
offset:
name: offset
in: query
description: >-
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.'
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
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
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
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_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_path_gid:
name: status_gid
in: path
required: true
description: The status update to get.
schema:
type: string
example: '321654'