-
Notifications
You must be signed in to change notification settings - Fork 18
/
Copy pathapiary.apib
7641 lines (6360 loc) · 287 KB
/
apiary.apib
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
FORMAT: 1A
HOST: https://tenant.acrolinx.cloud
# Acrolinx API
The REST-like Acrolinx API helps you:
* Configure settings on your Acrolinx instance
* Retrieve information from your Acrolinx instance
* Build Acrolinx checking features into your content creation workflows.
## Acrolinx SDKs
Consider using [Acrolinx SDKs](https://github.com/acrolinx?q=sdk).
# Authentication and Authorization
To interact with Acrolinx, you must use authorized and authenticated. This requires an **access token**.
An **access token** is an encoded and cryptographically signed string. It has the following characteristics:
* It's associated with a user
* A user can have an infinite number of access tokens
* It has a certain lifetime (30 days default) that you can change
* It expires after the lifetime or when the password of the associated user is changed
* It provides authorization and authentication
Get an **access token**
To get an access token, sign in to Acrolinx.
**Note:** To learn more about creating API tokens, read [Create an API Token](https://support.acrolinx.com/hc/en-us/articles/10306041244818-Create-an-API-Token) in the Acrolinx documentation.
See also [Create an API token](#Create an API token (Self)).
Use an access token:
Every request you send to the Acrolinx API must contain a [header](#header-access-token) that includes an access token:
```
X-Acrolinx-Auth: WERTZUIOP
```
## API token
An API token is an access token with special characteristics:
* It has a lifetime of 4 years
* It does **not expire when the password of the associated user is changed**
* A user can have only one API token associated with it at a time
To get an API token:
* Go to your Settings and create one.
* Use the **user API** programmatically. (See more under the section **User-generated API tokens**)
Besides that, the **API token** works like an **access token**.
# General headers
## Access token
All methods except "index" and "poll access token" require a valid access token in the `X-Acrolinx-Auth` header.
If the token is invalid, Acrolinx returns a `401` response. (see `401` response of "index").
Example:
```
X-Acrolinx-Auth: 123579080a8d1fee12490a90dc3
```
## Base URL
To support reverse proxies, an integration may provide the `X-Acrolinx-Base-Url` header with each request. If the response body contains links to the API,
Acrolinx will prefix them with the specified value. The value must be an absolute URL including scheme and host.
Malformed values will result in a `400` status code.
Example:
```
X-Acrolinx-Base-Url: https://example.com/path/
```
## Integration locale
All methods accept a header `X-Acrolinx-Client-Locale` that the integration can use to identify its own locale (for example, UI language).
For the value of the header field, use a single language tag that complies with [BCP 47](https://www.ietf.org/rfc/bcp/bcp47.txt). Acrolinx will try to return message strings
and other locale-specific parts of the response in the requested language.
Example:
```
X-Acrolinx-Client-Locale: de-CH
```
Acrolinx tries to match to the nearest configured locale that it support, for example, `de`.
The "index" request returns a list of supported locales. Acrolinx falls back to the default `en` locale under the following conditions:
* No X-Acrolinx-Client-Locale header is sent
* There's no matching supported locale
* For the given response, there's no appropriate localization available
## Signature
If not otherwise documented, all methods require you to set a header `X-Acrolinx-Client`. The header needs to include a valid signature.
If the header is missing or if the signature is invalid, the request returns an error.
The format of the signature is `Signature;Version`, where `Signature` is the signature as configured in the Acrolinx license and
`Version` is the version number of the integration.
Example:
```
X-Acrolinx-Client: SW50ZWdyYXRpb25EZXZlbG9wbWVudERlbW9Pbmx5; 1.0.1.45
```
# Response format
The API provides a consistent format for all responses. Each response has a `links` field and one of the three fields: `error`, `progress`, or `data`.
The `links` field contains further URLs that you can use as a next step in the workflow.
* `error` is set if the request didn't succeed. This includes an HTTP status code greater or equal to 4xx.
* `progress` means that the processing isn't done yet and the integration has to poll for the final result.
* `data` contains the actual result data. The processing finished successfully.
## Error responses
### General format
The API provides a consistent format for errors, which is based on [RFC7807](https://datatracker.ietf.org/doc/rfc7807/?include_text=1).
The format is JSON and the API guarantees to send the fields `type`, `title`, `detail`, and `status` with each error response.
Example:
```
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
{
"error": {
"type": "auth",
"title": "Invalid authentication",
"detail": "The provided token for authorization is not valid.",
"status": 403
}
"links": {}
}
```
* `type` is a unique identifier for the type of error. Choose a workflow for error handling that works best for the type of integration (interactive or automated).
* `title` is a short description of the error. You can use this as the title of the error message that users see.
* `detail` is a longer description of the error. You can also include this in the error message.
* `status` is redundant to the HTTP status code. It may be helpful if a proxy changes the HTTP status code of the original API response.
* You might also see an optional `reference` field with an ID.
Depending on `type`, the response may include additional fields to provide more detailed information.
We may add additional fields in the future. An integration must not break because of unexpected fields.
### Error types
Type | Description| What to do
-----|------------|------------
`client` | Unspecific error caused by the integration's request. | Check logs and configuration or the integration code.
`server` | Unspecific Acrolinx error during processing of a request. | Check logs and configuration.
`clientSignatureMissing` | The `X-Acrolinx-Client` header was missing. | [Contact Acrolinx](https://support.acrolinx.com/hc/en-us/requests/new) to learn how to get a valid signature.
`clientSignatureRejected` | The signature included in the `X-Acrolinx-Client` header was invalid. | [Contact Acrolinx](https://support.acrolinx.com/hc/en-us/requests/new) to get a valid signature.
`sso` | Returned for any single sign-on errors. | This is likely a configuration issue.
`auth` | Invalid authentication. | Use another access token.
`insufficientPrivileges` | Insufficient privileges. | Assign the required privileges to the user.
`interactiveSignInTimedOut` | The interactive sign-in process timed out. | Sign in again.
`checkCancelled` | The check was canceled. No result is available. | Probably points to an error in the integration.
`checkFailed` | The check failed. | Check logs and configuration.
`invalidBaseUrl` | The request contained an invalid base URL in the `X-Acrolinx-Base-URL` header. | Check the configuration of integration or proxies, which set the header.
`customFieldsIncorrect` | Custom field values are incorrect. | Provide valid values for all required custom fields before or when checking a document.
`validation` | Invalid request attributes. | Check the request for invalid values or missing parameters.
`guidanceProfileDoesntExist` | Style guide doesn't exist. | The style guide doesn't exist or isn't available for the user ID and language provided.
`noGuidanceProfileConfigured` | No style guide configured. | No style guide is configured for the user ID and language provided.
`contentTooLarge` | File too large. | Try checking less content.
`queueLimitExceeded` | Queue limit exceeded. | Wait at least as long as suggested in the retry-after header and try another check.
`conflict` | Concurrent write access. | Conflict with a concurrent write access. Try again with fresh data.
`licenseLimitExceeded` | License limit exceeded. | You exceeded a limit set by the terms of your license. The error description contains more details. For more information, check [the documentation](https://support.acrolinx.com/hc/en-us/articles/10306079192082-License-Types).
`entityToAssociateNotFound` | One or more associates to an entity could not be found. | Make sure that the given associates actually exist.
### Additional information on validation errors
Errors with type `validation` come with a list of constraint violation descriptions in an additional property `validationDetails`:
```
{
"title": "Validation error",
"constraint": "The 'languageId' is required.",
"attributePath": "submit.arg1.languageId",
"detail": "The 'languageId' is required but was 'null'.",
"invalidValue": "DictionaryEntry{surface='TestSurface', scope=language, languageId='', guidanceProfileId='null', documentId='null'}",
"possibleValues": ["en", "de"]
}
```
* `title`: "Validation error"
* `constraint`: A minimal description of the constraint that was violated.
* `attributePath`: A hint about the property or parameter that had an invalid value.
* `detail`: A more detailed description of the constraint violation.
* `invalidValue`: The value that was invalid. Can be a data structure.
* `possibleValues`: An optional list of valid values for the property.
The `validationDetails` provide developers with information to troubleshoot bad requests.
They are not intended for automated consumption.
There's no guarantee that values are always present or in a uniform format.
## Progress responses
A progress response always contains a `retryAfter` field, which tells the integration how many seconds to wait until the next poll request.
The response can optionally include both the `message` field with a human-readable text about the current status and a `percent`, which is
a number that shows the progress as a percent.
A progress response always has the `Retry-After` header set with the same value as the `retryAfter` field and an HTTP status 202.
Examples:
```
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"progress": {
"message": "The request is queued on position 5.",
"percent": 2,
"retryAfter": 5
}
"links": {
"cancel": "https://tenant.acrolinx.cloud/api/v1/checks/ID100"
}
}
```
```
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"progress": {
"retryAfter": 1
}
"links": {}
}
```
## Successful responses
The number of fields in successful response data depends on the request. For example, the response might contain additional fields if the
original check request also asked for a Term Harvesting report.
Example:
```
HTTP/1.1 200 Ok
Content-Type: application/json
{
"data": {
"score": 99,
"textualScore": "Good job!"
}
"links": {
"submit": "https://tenant.acrolinx.cloud/api/v1/checks"
}
}
```
# HTML fields
Responses may contain fields with HTML snippets that provide nice formatting in interactive integrations. These fields have a name that ends with "Html", for example, "guidanceHtml". Related fields with the same content may appear in plain text. If such a field exists, it will end with "Text" like in the example, "guidanceText".
All HTML fields only contain formatting tags that do not pose a security risk. A server-side allow list filters all tags.
# JSON - Escape special characters
Some JSON characters are special and require escaping. To escape a character, prefix the character with a backslash `\`.
Below are some common characters that need to be escaped in JSON:
|Character|Escape character|
|----------------|------------|
|Double quote|`\"`|
|Backslash|`\\`|
|Forward slash|`\/`|
|Backspace|`\b`|
|Form feed|`\f`|
|Newline|`\n`|
|Tab|`\t`|
|Unicode escape sequence for special characters|`\uXXXX`|
Example:
The value of the password is `backslash\quote"` in the JSON below. The special characters are escaped using a backslash.
```json
{
"username": "username",
"fullName": "full Name",
"password": "backslash\\quote\""
}
```
# Group Index
## Index [GET /api/v1]
This endpoint returns general information about the current Acrolinx
version. Starting with version 2024.09, it also contains
information about the installed linguistic configuration (referred to as a "guidance package").
**Note**: This is the only web service method that provides a 200 response if no access token was sent.
+ Request
+ Header
X-Acrolinx-Auth: ""
+ Response 200 (application/json)
{
"data": {
"platform": {
"name": "Acrolinx Platform",
"version": "2024.09.10156"
},
"server": {
"name": "Core Server",
"version": "2024.09.10846"
},
"guidancePackage": {
"name": "Guidance Package for ACME",
"version": "2024.09",
"build": "7732",
"date": "2024-09-13"
},
"locales": [ "en" ]
},
"links": {
"signIn": "https://tenant.acrolinx.cloud/api/v1/auth/sign-ins"
}
}
+ Request
+ Header
X-Acrolinx-Auth: 123579080a8d1fee12490a90dc3
+ Response 200 (application/json)
{
"data": {
"platform": {
"name": "Acrolinx Platform",
"version": "2024.09.10156"
},
"server": {
"name": "Core Server",
"version": "2024.09.10846"
},
"guidancePackage": {
"name": "Guidance Package for ACME",
"version": "2024.09",
"build": "7732",
"date": "2024-09-13"
},
"locales": [ "en" ]
},
"links": {
"signIn": "https://tenant.acrolinx.cloud/api/v1/auth/sign-ins",
"submitCheck": "http://tennant.acrolinx.cloud/api/v1/checking/checks"
}
}
+ Response 401 (application/json)
{ // if provided access token became invalid
"error": {
"type": "auth",
"title": "Invalid access token",
"detail": "The provided token for authorization is invalid.",
"status": 401
},
"links": {}
}
## Capabilities [GET /api/v1/capabilities]
Learn about capabilities of the individual APIs. This overview helps if you want to
use more than one feature of the API.
+ Response 200 (application/json)
+ Attributes
+ data (object)
+ checking (object) - capabilities of the checking resource
+ document (object) - capabilities of the document resource
+ links (object)
# Group Authentication API
Authentication works with either a configured access token, with single sign-on (SSO), or interactively with the Acrolinx sign-in web page.
Embedded integrations use either the configured access token or SSO.
Interactive integrations with a human user use SSO or the interactive process.
## Request or validate an API token [POST /api/v1/auth/sign-ins]
The sign-in collection allows Acrolinx API integrations to request user authentication and to check
the validity and privileges of existing access tokens.
If Acrolinx is configured for single sign-on, then this endpoint will accept the configured credentials
to authenticate the request.
+ Request (application/json)
+ Header
X-Acrolinx-Auth: 123579080a8d1fee12490a90dc3 (valid) OR (invalid/expired access token) OR (no access token)
X-Acrolinx-Client-Locale: ja
X-Acrolinx-Client: QWxlU2hNyb2bHVnLWlunhQyR29Rm9xpbvZ2lZXRz; 1.0.1.45;
+ Response 200 (application/json)
No sign-in needed, the response body will contain valid access tokens.
Acrolinx may decide that the request is already sufficiently authorized. In this case,
no sign-in process is started. The response will contain the same information as after
a successful sign-in. The following conditions may lead to this response:
- The `X-Acrolinx-Auth` header contained a valid token.
- Single sign-on is configured and valid credentials are provided.
+ Attributes (object)
+ Response 201 (application/json)
If the `X-Acrolinx-Auth` header is absent a
new sign-in process is started. The response body contains two links.
One allows the user to complete the sign-in process.
The other helps the integration to acquire the session data:
- `interactive` a link to a web page that allows the user to authenticate and
permit the integrations to access Acrolinx. If you provide a language in the
`X-Acrolinx-Client-Locale` header, the link will point to a localized
version of that web page if available and technically possible.
- `poll` a link to a resource that will return an *access token* and information
about the user after sign-in. (see [GET `api/v1/auth/sign-ins/{id}`](#authentication-api-poll-for-a-new-api-token-get))
Note that the sign-in process will time out. The `interactiveLinkTimeout` field
contains the length of time in seconds that the `interactive` link will stay valid. If the
sign-in page was loaded before this time, Acrolinx will extend
the timeout. To detect timeouts after opening the sign-in page, use the `poll` link.
+ Body
{
"data": {
"state": "Started",
"interactiveLinkTimeout": 900
},
"links": {
"interactive": "https://tenant.acrolinx.cloud/dashboard.html?login=19901-2-8412998412",
"poll": "https://tenant.acrolinx.cloud/api/v1/auth/sign-ins/185-0ijfgklejt2390tui"
}
}
+ Attributes
+ data
+ `state`:`Started` (string, required)
+ `interactiveLinkTimeout`: 900 (number, required)
+ links
+ `interactive`: `https://tenant.acrolinx.cloud/dashboard.html?login=19901-2-8412998412` (string, required)
+ `poll`: `https://tenant.acrolinx.cloud/api/v1/auth/sign-ins/185-0ijfgklejt2390tui` (string, required)
+ Response 401 (application/json)
If invalid SSO credentials are supplied, the request is rejected. This occurs when an SSO username
is present but the SSO password is wrong, missing, or the user couldn't be created.
+ Header
WWW-Authenticate: ACROLINX_TOKEN, ACROLINX_SIGN_IN (, ACROLINX_SSO)
+ Attributes (object)
+ Response 503
Acrolinx is unable to start a sign-in process at this time.
+ Header
Retry-After: 30
+ Attributes (object)
## Poll for a new API token [GET /api/v1/auth/sign-ins/{id}]
Use polling so your integration waits for a user to authenticate and authorize before the integration can use the
Acrolinx API. Once the user has completed the sign-in process, the response will return a new access token.
When polling returns a final result, the polling endpoint will disappear and return a `NOT FOUND` status.
+ Parameters
+ id: `99576707-ed8c-44b6-82b8-c3ced8f349d1` (string, required) - poll-id for the authorization request
+ Request
+ Header
X-Acrolinx-Client: QWxlU2hNyb2bHVnLWlunhQyR29Rm9xpbvZ2lZXRz; 1.0.1.45
+ Response 200 (application/json)
A user completed the sign-in process and Acrolinx created a new access token.
Note that this resource will disappear after this response.
+ Attributes (object)
+ Response 202 (application/json)
The user hasn't authorized the sign-in yet. Request the same URI again to continue polling.
Note that integrations should pace themselves by respecting the `Retry-After` header.
+ Header
Retry-After: 2
+ Attributes
+ progress
+ `retryAfter`: 2 (number, required)
+ Response 404 (application/json)
Acrolinx has no knowledge of the polling token. If you used a valid poll URI, the cause of this response is
a timeout, or another poll request may have consumed the credentials.
The returned type is `interactive_sign_in_timed_out`, which distinguishes this response from a normal 404 caused by a wrong URL.
+ Attributes
+ error
+ `type`: `interactive_sign_in_timed_out` (string, required)
+ `status`: 404 (number, required)
+ title: `The interactive sign-in process timed out` (string, required)
+ detail: `The interactive sign-in process timed out. Please start a sign-in.` (string, required)
# Group Checking API
The API for checking documents.
## List checking capabilities [GET /api/v1/checking/capabilities]
Use the checking capabilities to fetch a list of available style guides. If sublanguages are activated, they're included in the list of style guides.
For each style guide, Acrolinx provides information about the language, activated goals, and term sets. The integration may use this information
for filtering, but users can only select one style guide for checking. You cannot deselect individual goals within a style guide.
For each style guide, the goals contain an additional string field called `scoring`, which can have one of the following values:
* `required` (this goal counts towards the score and writers should prioritize issues found in this goal when creating content).
* `recommended` (this goal is a recommendation only and does not count towards the overall document score).
**Note:** Before you get started with the Checking API, review the [authentication and authorization](https://acrolinxapi.docs.apiary.io/#introduction/authentication-and-authorization) requirements.
+ Request
+ Headers
X-Acrolinx-Auth: your_access_token
X-Acrolinx-Client: your_client_signature
+ Response 200 (application/json)
{
"data": {
"guidanceProfiles": [
{
"id": "aud-1",
"displayName": "Tom the Technical Type",
"language": {
"id": "en-gb",
"displayName": "English (Great Britain)"
},
"goals": [{
"id": "CORRECTNESS",
"displayName": "Correctness",
"color": "#00bfa5",
"scoring": "required"
},
{
"id": "CLARITY",
"displayName": "Clarity",
"color": "#ec407a",
"scoring": "recommended"
},
{
"id": "WORDS_AND_PHRASES",
"displayName": "Words and Phrases",
"color": "#ea80fc",
"scoring": "required"
}],
"termSets": [{
"displayName": "Switches"
},
{
"displayName": "Acrolinx"
}]
},
{
"id": "aud-2",
"displayName": "Randolf Redakteur",
"language": {
"id": "de",
"displayName": "German"
},
"goals": [{
"id": "CORRECTNESS",
"displayName": "Correctness",
"color": "#00bfa5",
"scoring": "required"
}],
"termSets": []
}
],
"contentFormats": [
{
"id": "auto",
"displayName": "Automatic Detection"
},
{
"id": "text",
"displayName": "Plain Text"
},
{
"id": "markdown",
"displayName": "Markdown"
},
{
"id": "xml",
"displayName": "XML"
},
{
"id": "word_xml",
"displayName": "XML (MS Word 2003)"
}
],
"contentEncodings": [ "none", "zip,base64", "base64" ],
"referencePattern": "\\.(xml|xhtm|xhtml)$|\\.(md|markdown|mdown|mkdn|mkd)$|\\.(docx|docm|pptx|pptm|xlsx|xlsm)$|\\.txt$",
"checkTypes": [ "batch", "interactive", "baseline", "automated" ],
"reportTypes": ["extractedText", "termharvesting", "scorecard"]
}
}
## Submit a check [POST /api/v1/checking/checks]
Submits a document for checking. After you upload a document, Acrolinx schedules the check. Once checking completes,
Acrolinx makes the results available. The following steps summarize how to use the checking API:
* Submit a check
* Poll for progress
* Download check results
To learn what file types Acrolinx supports, see the list of
[supported input types](https://support.acrolinx.com/hc/en-us/articles/10211264846482-Supported-Input-Types).
The same information is available in the checking capabilities.
+ Request (application/json)
+ Headers
X-Acrolinx-Auth: your_access_token
X-Acrolinx-Client: your_client_signature
+ Body
// A minimal request declaring the format only:
{
"content": "text to check", // required
"checkOptions": {
"contentFormat": "markdown", // recommended, default: auto
},
}
// A minimal request using a document reference to tell the format:
{
"content": "text to check", // required
"document": { // recommended, default: empty "document" object
"reference": "C:\\abc.md", // recommended, used to determine the input format and correlate multiple checks of the same document
}
}
// If a standard format is configured in Acrolinx, the minimal request is even shorter:
{
"content": "text to check", // required
}
// A request can be much more specific, this is the full set of attributes:
{
"content": "text to check", // required
"contentEncoding": "base64", // optional, default: none = HTTP request encoding
"checkOptions": {
"guidanceProfileId": "aud-1", // optional, default: first guidance profile. optional target name/target id, default: detected by Automatic Target Assignment
"reportTypes": ["scorecard"], // optional, default: scorecard
"contentFormat": "markdown", // optional, default: auto
"checkType": "batch", // optional, default: interactive
// The available check types include:
// interactive = an individual user checked a single file from an integration
// batch = an individual user checked multiple files from an integration
// baseline = an individual user initiated a check for a shared repository of files from a repository integration
// automated = a check of a single file initiated automatically (for example, by using a git hook)
// To learn more about the available check types, [visit the Acrolinx coding guidance](https://github.com/acrolinx/acrolinx-coding-guidance/blob/main/topics/check-types.md).
"partialCheckRanges": [{ "begin": 10, "end": 20 }, { "begin": 40, "end": 70 }], // makes the check a partial check
"batchId": "gen.clc.159203590" // only for batch checks; optional;
},
"document": { // optional, default: empty "document" object
"reference": "C:\\abc.md", // optional integration known id hint e.g. a file name
"customFields": [ // optional
{
"key": "field1",
"value": "value1"
},{
"key": "field2",
"value": "value2"
}
]
},
"language": "en" // optional: force language for Target Assignment using
// guidanceProfile.language.id codes (see
// checking capabilities)
// default: target language if target is set in checkOptions.guidanceProfileId,
// otherwise auto-detected
}
+ Response 201 (application/json)
{
"data": {
"id": "AB-153"
},
"links": {
"result": "https://tenant.acrolinx.cloud/api/v1/checking/checks/AB-153",
"cancel": "https://tenant.acrolinx.cloud/api/v1/checking/checks/AB-153"
}
}
+ Response 400 (application/json)
{
"error": {
"detail": "The guidance profile doesn't exist or isn't available for the user id and language given.",
"type": "content_goal",
"title": "guidance profile doesn't exist",
"status": 400
},
"links": {
}
}
## Check result [/api/v1/checking/checks/{id}]
### Check result guide
#### Ignore all issue occurrences
Every issue in the check result has the attribute `positionalInformation.hashes.issue`. Use this attribute to find all occurrences of an issue. Users can ignore all of these issues together.
The integration also remembers the `positionalInformation.hashes.issue` attribute after an ignore-all operation. This information lets you filter out all previously ignored occurrences of an issue after a recheck.
#### Replace all issue occurrences with a suggestion
Every issue in the check result has the attribute `positionalInformation.hashes.issue`. Use this attribute to find all occurrences of an issue.
To apply a suggestion to all occurrences of an issue, use the `groupId` attribute to find the corresponding suggestion.
If an occurrence of an issue doesn't have a suggestion with the same `groupId` or if the `groupId` is empty, then you can't replace it with a replace-all operation.
Note that not all occurrences of an issue always have the same suggestions. When this happens, the replace-all operation only applies to issues with the same suggestion.
### Poll check result [GET]
Polls the check result. Acrolinx either returns a progress response or the completed result. The URL for the request is in the "result" link of the submitted check.
+ Parameters
+ id: `AB-153` (required, string) - the check id
+ Request
+ Headers
X-Acrolinx-Auth: your_access_token
X-Acrolinx-Client: your_client_signature
+ Response 202 (application/json)
+ Headers
Retry-After: 2
+ Body
{
"progress" : {
"percent": 20,
"message": "Waiting in queue",
"retryAfter": "2"
}
}
+ Response 200 (application/json)
Attention: which attributes the response contains depends on
the configuration, request, and document.
{
"data":{
"id": "AB-153",
"checkOptions": {
"guidanceProfileId": "aud_1",
"guidanceProfileName": "Acrolinx Essentials",
"languageId": "en",
"termSets": [{
"displayName": "Switches"
},
{
"displayName": "Acrolinx"
}],
"reportTypes": ["scorecard", "termharvesting"],
"contentFormat": "markdown",
"checkType": "interactive",
"partialCheckRanges": [{ "begin": "10", "end": "20" }, { "begin": "40", "end": "70" }],
"confidential": false
},
"document": {
"id": "283ab1e075f21a",
# DRAFT ------START------
"contentType": "E-Mail",
# DRAFT ------END------
"customFields": [
{
"displayName": "Project ID",
"key": "projectId",
"value": "Marketing Campaign",
"required": true
}
],
"displayInfo": {
"reference": "abc.md"
}
},
"quality": {
"score": 81,
"status": "red",
"scoresByStrategy": [
{
"id": "average",
"score": 81
},
{
"id": "minimum",
"score": 78
}],
"scoresByGoal": [
{
"id": "CORRECTNESS",
"score": 83
},
{
"id": "CLARITY",
"score": 64
},
{
"id": "WORDS_AND_PHRASES",
"score": 78
}],
"metrics": [
{
"id": "Clarity index",
"score": 100
},
{
"id": "Informality index",
"score": 47
},
{
"id": "Liveliness index",
"score": 50
},
{
"id": "Flesch Reading Ease",
"score": 36
}]
},
"counts": {
"issues": 4,
"scoredIssues": 2, // **Since Acrolinx 2020.11**
"sentences": 10,
"words": 121
},
"goals": [{
"id": "CORRECTNESS",
"displayName": "Correctness",
"color": "#00bfa5",
"scoring": "required",
"issues": 1
},
{
"id": "CLARITY",
"displayName": "Clarity",
"color": "#ec407a",
"scoring": "recommended",
"issues": 2
},
{
"id": "WORDS_AND_PHRASES",
"displayName": "Words and Phrases",
"color": "#ea80fc",
"scoring": "required",
"issues": 1
}],
"issues": [
{
"goalId": "CORRECTNESS",
"guidelineId": "EN20111291451MK",
"internalName": "title_case_chicago",
"displayNameHtml": "Use Chicago style for the title case?",
"guidanceHtml": "<div class=\"shortHelp\" lang=\"en\" xml:lang=\"en\">\n<p>According to the <q>Chicago Manual of Style</q>, here's how you write titles:</p>\n<ul>\n<li>Capitalize the first word and the last word.</li>\n<li>Capitalize all \"main\" words.</li>\n<li>Don't capitalize articles and conjunctions (example: <q>a</q>, <q>and</q>).</li>\n<li>Don't capitalize prepositions independent of their length (example: <q>about</q>, <q>around</q>).</li>\n</ul>\n</div>",
"displaySurface": "zentense",
"canAddToDictionary": true,
"issueType": "actionable", // possible values: actionable, analytical (since 2021.02)
"positionalInformation": {
"hashes": {
"issue": "BhKh3iaGBjB7Cw6M/GwrLQ==",
"environment": "vJ9eCVViEpIdM76h+5K/nA==",
"index": "hjlRLT0K+LlvlslKdNUlhw==1"
},
"matches": [{
"extractedPart": "zen",
"extractedBegin": 30,
"extractedEnd": 33,
"originalPart": "zen",
"originalBegin": 19247,
"originalEnd": 19255
}, {
"extractedPart": "te",
"extractedBegin": 33,
"extractedEnd": 35,
"originalPart": "&te;",
"originalBegin": 19250,
"originalEnd": 19254
},{
"extractedPart": "nse",
"extractedBegin": 35,
"extractedEnd": 38,
"originalPart": "nse",
"issueLocations": [
{
"locationId": "pageLocation",
"displayName": "Page 4",
"values": { "page": "4" }
}
],
"suggestions": [
{
"surface": "sentence",
"groupId": "sentence",
// the replacements refer to the matches entry of the same Index
// null means, don't change, any other value including the empty string means, replace the match
"replacements": ["sen",null,"nce"],
"iconId":"preferred" // optional icon id for terminology issues, "preferred" or "admitted"
}
}],
"links":
{
"termContribution": "https://tenant.acrolinx.cloud/terminology/v7/rest/contribute",
"termContributionInteractive": "https://tenant.acrolinx.cloud/termcontribution.html?surface=@@base64:cXdlcnR5dWlvcA==&locale=en&language=en&userid=admin&context=@@base64:VGhpcyBzZW50ZW5jZSBoYXMgYSBxd2VydHl1aW9wLg==",
"addToDictionary": "https://tenant.acrolinx.cloud/api/v1/dictionary/submit",
"help":"https://tenant.acrolinx.cloud/htmldata/en/rules/help/title_case_chicago.html"
}
},
{
"goalId": "WORDS_AND_PHRASES",
"guidelineId": "b4a5192e-5f9e-4f10-a849-a16be4b9cb18",
"internalName": "term_flag",
"displayNameHtml": "<b>Illegal sublanguage variant</b> of preferred term",
"guidanceHtml": "<div class=\"guidance term\">\n\t<b>Domains</b>\n\t\t\t<br/><i>Switches</i>\n\t\t\t\t\t<br/>\n\t\t<b>Note</b>\n\t\t<br/>\n\t\tUse 'please' in presale materials only. Do NOT use 'please' in postsale material.\n\t</div>\n",
"canAddToDictionary": false,
"issueType": "actionable",
"displaySurface": "Please",
"positionalInformation": {
"hashes": {
"issue": "3qyt/AVxwNTOUQSuMA7brw==",
"environment": "TiwIFBwA6X920mDAezJTyQ==",
"index": "Lm9PqBGGm+tj21rt3pkpjA==1"
},
"matches": [{
"extractedPart": "Please",
"extractedBegin": 766,
"extractedEnd": 772,
"originalPart": "Please",