Edit in GitHubLog an issue

Projects Overview

The CJA APIs allow you to retrieve, update, or create projects programmatically through Adobe I/O. The APIs use the same data and methods that are used when working with projects in the UI. For more information on understanding project definition data architecture, see the Project Definition article that accompanies this user guide. See Workspace projects overview in the CJA documentation for more information.

Best Practices#

Please follow these guidelines when using the Projects APIs:

  • Make multiple, smaller requests instead of a large, single request.
  • Request data once and cache it.
  • Use caution when updating a project so that you do not alter the original project used by others.
  • Avoid creating duplicate projects with the same definition. Creating many projects will affect performance for your company in some situations.
  • If possible use the Analytics UI for creating projects from scratch. The UI offers significant advantages for managing and optimizing the complexity of this task. If you need to create projects programmatically, it is usually easier to create a template project in the UI and then have your application change only small portions of the project definition.

Creating Projects#

As mentioned in the Best Practices section above, the CJA UI is recommended for creating projects from scratch. If you do choose to use the API to create projects, keep in mind that certain fields cannot be supplied via the POST /projects endpoint. For example, tags are not stored within the projects themselves and will therefore be ignored if supplied on a creation request.

/projects Endpoint Description#

The /projects endpoint description is shown in our Swagger UI. Use the Swagger UI to see endpoint summaries, available methods, parameters, example values, models, and status codes, and to try out the API.

Expansions#

Projects endpoints support the URL query parameter expansion. This parameter allows specifying additional data fields to be populated in response objects. Available expansions are shown in the Swagger UI description. The following table describes expansion fields:

FieldDescription
ownerFullNameThe name of the owner of the project
modifiedThe date the project was last modified
tagsTags applied to the project
sharesShares applied to the project
accessLevelAccess level the current user has to a particular project (Edit/Duplicate/View)
externalReferencesAnalytics components (Segments, Calculated Metrics, Date Views) used in the project definition
definitionThe project definition

IncludeTypes#

The GET multiple /projects endpoint supports the query parameter includeType. This parameter alters the set of projects that are included in API responses. By default, responses without this parameter include only projects owned by the user making the request. When using this parameter, the following values are possible:

  • all: Returns all projects linked to this company - this includeType is only available to admin users
  • shared: Returns projects shared with the user

Locale#

Project endpoints support the URL query parameter locale. Supported values are en_US, fr_FR, jp_JP, ja_JP, de_DE, es_ES, ko_KR, pt_BR, zh_CN, and zh_TW. This query parameter specifies the language for responses.

Pagination#

Any response that can return multiple projects can be paginated with the page and limit URL query parameters. The limit parameter indicates the size of the desired page, and the page parameter indicates which page you want. A maximum page size of 1000 is enforced.

Example cURL Request#

The following example requests all projects on page 0 with page size 10:

GET https://cja.adobe.io/projects

Example Response#

The following response 10 projects owned by the caller on the first page:

Copied to your clipboard
1
2{
3 "content": [
4 {
5 "id": "6091a10005c7706c0acdd751",
6 "name": "New Project",
7 "description": "",
8 "dataId": "dv_000000000000000000",
9 "owner": {
10 "imsUserId": "0000000000000000000@AdobeID"
11 },
12 "type": "project",
13 "created": "2021-05-04T19:31:12Z"
14 },
15 {
16 "id": "6094a7e01936af351300b81b",
17 "name": "New Project",
18 "description": "",
19 "dataId": "dv_000000000000000000",
20 "owner": {
21 "imsUserId": "0000000000000000000@AdobeID"
22 },
23 "type": "project",
24 "created": "2021-05-07T02:37:20Z"
25 },
26 {
27 "id": "6094aa6b318ae31bf7d0a052",
28 "name": "New Project",
29 "description": "",
30 "dataId": "dv_000000000000000000",
31 "owner": {
32 "imsUserId": "0000000000000000000@AdobeID"
33 },
34 "type": "project",
35 "created": "2021-05-07T02:48:11Z"
36 },
37 {
38 "id": "609c001c17d70a6b31694b7b",
39 "name": "New Project",
40 "description": "",
41 "dataId": "dv_000000000000000000",
42 "owner": {
43 "imsUserId": "0000000000000000000@AdobeID"
44 },
45 "type": "project",
46 "created": "2021-05-12T16:19:40Z"
47 },
48 {
49 "id": "609d94557a1bac32bfe822d6",
50 "name": "New Project",
51 "description": "",
52 "dataId": "dv_000000000000000000",
53 "owner": {
54 "imsUserId": "0000000000000000000@AdobeID"
55 },
56 "type": "project",
57 "created": "2021-05-13T21:04:21Z"
58 },
59 {
60 "id": "609d9b7117d70a6b31699d63",
61 "name": "New Project",
62 "description": "",
63 "dataId": "dv_000000000000000000",
64 "owner": {
65 "imsUserId": "0000000000000000000@AdobeID"
66 },
67 "type": "project",
68 "created": "2021-05-13T21:34:41Z"
69 },
70 {
71 "id": "609eb9772ecede2233067197",
72 "name": "New Project",
73 "description": "",
74 "dataId": "dv_000000000000000000",
75 "owner": {
76 "imsUserId": "0000000000000000000@AdobeID"
77 },
78 "type": "project",
79 "created": "2021-05-14T17:55:03Z"
80 },
81 {
82 "id": "60a400cfad861025de7edf25",
83 "name": "New Project",
84 "description": "",
85 "dataId": "dv_000000000000000000",
86 "owner": {
87 "imsUserId": "0000000000000000000@AdobeID"
88 },
89 "type": "project",
90 "created": "2021-05-18T18:00:47Z"
91 },
92 {
93 "id": "60a403292ecede223306ffe3",
94 "name": "New Project",
95 "description": "",
96 "dataId": "dv_000000000000000000",
97 "owner": {
98 "imsUserId": "0000000000000000000@AdobeID"
99 },
100 "type": "project",
101 "created": "2021-05-18T18:10:49Z"
102 },
103 {
104 "id": "60a5777dad861025de7ee116",
105 "name": "New Project",
106 "description": "",
107 "dataId": "dv_000000000000000000",
108 "owner": {
109 "imsUserId": "0000000000000000000@AdobeID"
110 },
111 "type": "project",
112 "created": "2021-05-19T20:39:25Z"
113 }
114 ],
115 "totalPages": 10,
116 "totalElements": 94,
117 "number": 0,
118 "numberOfElements": 10,
119 "firstPage": true,
120 "lastPage": false,
121 "sort": [
122 {
123 "direction": "ASC",
124 "property": "id",
125 "ignoreCase": false,
126 "ascending": true
127 }
128 ],
129 "size": 10
130}
131

Retrieving a Single Project#

You can retrieve projects individually if you know the project id. To find the project id, you can refer to the report descriptions or find it by using the multiple projects endpoint.

Example Request#

The following example requests data on the project 6091a10005c7706c0acdd751:

GET https://cja.adobe.io/projects/6091a10005c7706c0acdd751

Example Response#

The following example shows the response data for the request on project 6091a10005c7706c0acdd751:

Copied to your clipboard
1{
2 "id": "6091a10005c7706c0acdd751",
3 "name": "New Project",
4 "description": "",
5 "dataId": "dv_000000000000000000",
6 "owner": {
7 "imsUserId": "0000000000000000000@AdobeID"
8 },
9 "type": "project",
10 "created": "2021-05-04T19:31:12Z"
11}

Deleting a Project#

If you delete a project, it is hidden from all users in all menus. Additionally, it is no longer returned when retrieving multiple projects in an API call.

Example Request#

The following example deletes project 6091a10005c7706c0acdd751:

DELETE https://cja.adobe.io/projects/6091a10005c7706c0acdd751

Example Response#

The following response shows the deletion status for project 6091a10005c7706c0acdd751:

Copied to your clipboard
1{
2 "result": "success"
3}

Updating a Project#

You can edit existing projects with the PUT /projects/{id} endpoint. Some fields cannot be edited on a project with the PUT endpoint, including tags and shares. Other fields, including owner, name, description, dataId, and definition, can be edited.

The PUT endpoint also supports partial updates. This means that instead of sending the entire JSON object to the API, you can simply send fields that you want to update. For example, if you only want to update the name, use the JSON {"name":"Updated name"}. The entire object is returned in the response, modified by the requested expansions.

Example Request#

The following example updates the project 6091a10005c7706c0acdd751 with a new name:

PUT https://cja.adobe.io/projects/6091a10005c7706c0acdd751

Copied to your clipboard
{"name":"{NAME UPDATE}"}

Example Response#

The following example shows the response with updated name data:

Copied to your clipboard
1
2{
3 "id": "6091a10005c7706c0acdd751",
4 "name": "{NAME UPDATE}",
5 "description": "",
6 "dataId": "dv_000000000000000000",
7 "owner": {
8 "imsUserId": "0000000000000000000@AdobeID"
9 },
10 "type": "project",
11 "created": "2021-05-04T19:31:12Z"
12}
13

Validate Endpoint#

Because data views can have different configurations, variables, or metrics, one project that is valid in one report suite may not be valid in another. To determine which projects to use in different data views, you can use the validate endpoint. This endpoint allows you to POST a definition along with a target dataId. The validate endpoint responds with compatibility information on the project.

Example Request#

The following example requests validation for the project with dataId: dv_000000000000000000. The example shows a POST of the JSON definition:

POST https://cja.adobe.io/projects/validate

Copied to your clipboard
1{
2 "project": {
3 "id": "6091a10005c7706c0acdd751",
4 "name": "New Project",
5 "description": "",
6 "dataId": "dv_000000000000000000",
7 "owner": {
8 "id": 622291
9 },
10 "type": "project",
11 "definition": {
12 "additionalCuratedComponents": [],
13 "colorScheme": {
14 "id": "default",
15 "label": "",
16 "value": ["#00C0C7", "#5144D3", "#E8871A", "#DA3490", "#9089FA", "#47E26F", "#2780EB", "#6F38B1", "#DFBF03", "#CB6F10", "#268D6C", "#9BEC54", "#5EABFA", "#BE40CC", "#F56BB7", "#FEE02D"]
17 },
18 "countRepeatInstances": true,
19 "currentWorkspaceIndex": 0,
20 "customColorSchemes": [],
21 "isCurated": false,
22 "version": "31",
23 "viewDensity": "expanded",
24 "workspaces": [{
25 "id": "3B1FE317-C72A-4983-ABF1-D3BD14A8D511",
26 "name": "",
27 "panels": [{
28 "annotations": [],
29 "collapsed": false,
30 "dateRange": {
31 "id": "thisMonth",
32 "__entity__": true,
33 "type": "DateRange",
34 "__metaData__": {
35 "name": "This month"
36 }
37 },
38 "description": "",
39 "id": "C0DACAE8-CCE1-4332-9496-ABDBE80C9C23",
40 "name": "Freeform",
41 "position": {
42 "autoHeight": 374,
43 "autoSize": true,
44 "width": 100,
45 "x": 0,
46 "y": 0
47 },
48 "reportSuite": {
49 "id": "dv_000000000000000000",
50 "__entity__": true,
51 "type": "ReportSuite",
52 "__metaData__": {
53 "name": "dv name",
54 "rsid": "dv_000000000000000000"
55 }
56 },
57 "segmentGroups": [],
58 "subPanels": [{
59 "collapsed": false,
60 "description": "",
61 "id": "F2AAAA88-E63E-4AB6-9090-3612F378B9F0",
62 "isQuickInsightsSubPanel": false,
63 "linkedSourceId": "",
64 "position": {
65 "autoHeight": 222,
66 "autoSize": true,
67 "width": 100,
68 "x": 0,
69 "y": 0
70 },
71 "reportlet": {
72 "advancedMode": false,
73 "advancedSettings": {
74 "rows": [],
75 "tableState": "builder"
76 },
77 "columnTree": {
78 "_computedValues": [],
79 "dataSettings": {
80 "advancedItemLimit": 5,
81 "advancedItemSearch": {
82 "operator": "AND",
83 "rules": []
84 }
85 },
86 "id": "f46df4-2",
87 "name": "",
88 "nodes": [{
89 "_computedValues": [],
90 "component": {
91 "id": "All_Visits",
92 "__entity__": true,
93 "type": "Segment",
94 "__metaData__": {
95 "name": "All Visits"
96 }
97 },
98 "dataSettings": {
99 "advancedItemLimit": 5,
100 "advancedItemSearch": {
101 "operator": "AND",
102 "rules": []
103 }
104 },
105 "id": "f46df4-4",
106 "name": "All Visits",
107 "nodes": [],
108 "selectionCoordinates": [],
109 "tableCellDisplay": {
110 "conditionalFormattingOpts": {
111 "autoGenerate": true,
112 "usePercentLimits": false
113 },
114 "location": "behindNumber",
115 "type": {
116 "anomaly": true,
117 "background": true,
118 "backgroundType": "bar",
119 "comparison": "none",
120 "interpretZeroAsNoValue": false,
121 "number": true,
122 "percent": true,
123 "showGrandTotal": true,
124 "showSparklines": true,
125 "showTotals": true,
126 "wrapHeaderText": true
127 }
128 }
129 }],
130 "selectionCoordinates": [],
131 "tableCellDisplay": {
132 "conditionalFormattingOpts": {
133 "autoGenerate": true,
134 "usePercentLimits": false
135 },
136 "location": "behindNumber",
137 "type": {
138 "anomaly": true,
139 "background": true,
140 "backgroundType": "bar",
141 "comparison": "none",
142 "interpretZeroAsNoValue": false,
143 "number": true,
144 "percent": true,
145 "showGrandTotal": true,
146 "showSparklines": true,
147 "showTotals": true,
148 "wrapHeaderText": true
149 }
150 }
151 },
152 "freeformTable": {
153 "alignDatesForTimeDimension": true,
154 "attributionSettings": [],
155 "breakdowns": [],
156 "collapsed": false,
157 "columnWidths": [100, 100],
158 "pagination": {
159 "currentPage": 0,
160 "viewBy": 50
161 },
162 "search": {
163 "operator": "AND",
164 "rules": []
165 },
166 "selectionCoordinates": [],
167 "settings": {
168 "breakdownByPosition": false,
169 "rowBasedPercentages": false,
170 "totalsType": "columnSum"
171 },
172 "sort": {
173 "asc": false,
174 "columnId": "f46df4-4",
175 "labelColumn": false
176 },
177 "staticRows": [{
178 "component": {
179 "id": "metrics/visits",
180 "__entity__": true,
181 "type": "Metric",
182 "__metaData__": {
183 "name": "Visits"
184 }
185 },
186 "dataSettings": {
187 "advancedItemLimit": 5,
188 "advancedItemSearch": {
189 "operator": "AND",
190 "rules": []
191 }
192 },
193 "id": "f46df4-a"
194 }],
195 "statistics": {
196 "functions": [],
197 "ignoreZeros": true
198 }
199 },
200 "isConfigVisible": true,
201 "type": "FreeformReportlet"
202 },
203 "swatchColor": "#00C0C7",
204 "type": "genericSubPanel",
205 "visible": true,
206 "visualizationIndex": 1
207 }],
208 "type": "panel"
209 }]
210 }]
211 },
212 "created": "2021-05-04T19:31:12Z"
213 }
214}
215

Example Response#

The following response shows validation for the project with dataId: dv_000000000000000000.

Copied to your clipboard
1{
2 "valid": true,
3 "validatorVersion": "1.0.0"
4}
Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.