forked from acrolinx/platform-api
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathapiary.apib
1743 lines (1421 loc) · 68.1 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 Platform API
The Acrolinx Platform API is the new REST like API for accessing the Core Platform.
**NOTE:** All listed (future) features, which aren't yet or only partially implemented, are marked with the keyword DRAFT. Please consider this while using the Acrolinx Platform API!
# Authentication and Authorization
When using the Acrolinx Platform API, you'll need to be authorized and authenticated. This is done by providing an **Access Token**.
An **Access Token** is an encoded and cryptographically signed string. It has the following characteristics:
* It's bound to a user
* There can be an infinite number of Access Tokens per user
* It has a certain lifetime (default 30 days, can be changed)
* It will expire after the lifetime or when the password of the associated user is changed
* It provides authorization and authentication
How to get an **Access Token**?
You can get an Access Token by using the Acrolinx sign-in workflow.
(further description here)
How to use an Access Token?
Every request you're doing with the Acrolinx Platform API must contain a [header](#header-access-token) providing the Access Token:
```
X-Acrolinx-Auth: WERTZUIOP
```
## API Token
An API Token is an Access Token but with special characteristics:
* It has a lifetime of 4 years
* It will **not expire when the password of the associated user is changed**
* Only one API Token can be bound to a user at the time
You can get an API Token by accessing the user settings page on the Dashboard and generating one.
Other than that, the **API Token** functions as 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 even if not explicitly mentioned below.
If the token is invalid, a `401` response is returned (see `401` response of "index") even if this response isn't explicitly mentioned below.
Example:
```
X-Acrolinx-Auth: 123579080a8d1fee12490a90dc3
```
## Base URL
To support reverse proxies, a client may provide the `X-Acrolinx-Base-Url` header with each request. If the response body to the request
contains links into the Acrolinx API, the server will prefix them with the given value. The provided 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/
```
## Client Locale
All methods accept a header `X-Acrolinx-Client-Locale`, with which the client can identify its own locale (for example, UI language).
The value of the header field must be a single language tag that is compliant to BCP 47. The Acrolinx Platform 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
```
The server tries to match the sent locale to the closest locale that it's able to support, for example, `de`.
The "index" request returns the list of supported locales. The server falls back to the default `en` locale in the following cases:
* 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 a header `X-Acrolinx-Client` to be set. The header must be a valid signature. The request
returns an error, if the header is omitted or the given signature isn't valid.
The format of the signature is `Signature;Version;buildNumber`, where `Signature` is the signature as configured in the Acrolinx license and
`Version` is the version number of the client.
Example:
```
X-Acrolinx-Client: SW50ZWdyYXRpb25EZXZlbG9wbWVudERlbW9Pbmx5; 1.0.1.45
```
# Response Format
The API provides a consistent format for all responses. Each response as a field `links` and one of the three fields `error`, `progress`, `data`.
The `links` field contains further URLs that can be used as a next step in the workflow.
`error` is set, of the request didn't succeed. This is accompanied by an HTTP status code above or equal 4xx.
`progress` means, that the processing isn't yet finished and the client has to poll for the final result.
`data` contains the actual result data, the processing is successfully finished.
## 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`, `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. A client may choose a workflow for the error handling depending on the type.
* `title` is a short description of the error. It can be displayed to the user as title of the error.
* `detail` is a more verbose description of the error. It's suitable to be displayed to the user.
* `status` is redundant to the HTTP status code. It may be helpful in case a proxy changed the HTTP status code of the original API response.
* An optional `reference` field with an id may be present. If there, this id can be found in the Acrolinx log files to support better problem analysis.
Depending on `type`, additional fields may be part of the response providing more detailed information.
Additional fields may be added in future. A client must not break because of unexpected fields.
### Error Types
Type | Description| What to do
-----|------------|------------
`client` | Unspecific error caused by the client's request. | Check logs and configuration or the client code.
`server` | Unspecific error during processing of a request in Acrolinx. | Check logs and configuration.
`clientSignatureMissing` | The `X-Acrolinx-Client` header was missing. | Contact Acrolinx, how to acquire a valid license.
`clientSignatureRejected` | The given signature in the `X-Acrolinx-Client` header was invalid. | Contact Acrolinx, how to acquire a valid license.
`sso` | Returned for any single sign-on errors. | Most probably this is 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. | Start new.
`checkCancelled` | The check was canceled. No result is available. | Probably points to an error in the client.
`checkFailed` | The check failed. | Check logs and configuration.
`invalidBaseUrl` | The request contained an invalid base URL in the `X-Acrolinx-Base-URL` header. | Check configuration of client or proxies, which set the header.
`customFieldsIncorrect` | Custom field values are incorrect. |Please 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` | Guidance profile doesn't exist | The guidance profile doesn't exist or isn't available for the user id and language given.
`noGuidanceProfileConfigured` | No guidance profile configured | For the user id and language given no guidance profile is configured.
`contentTooLarge` | Content to large | Without reconfiguration of the Acrolinx platfrom the document can't be checked.
`queueLimitExceeded` | Queue limit exceeded | Retry to submit the check after waiting at least as long as suggested in the retry-after header.
`conflict` | Concurrent write access | Conflict with a concurrent write access. Retry the operation with fresh data.
`licenseLimitExceeded` | License limit exceeded | You exceeded a limit set by your licensing terms. The error description contains more details. Please check [the documentation](https://docs.acrolinx.com/coreplatform/latest/en/user-management/user-licenses) for more information.
### 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 towards 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` are intended as information for developers to troubleshoot bad requests.
They are not intended for automated consumption.
Values are not guaranteed to be always present or in a uniform format.
## Progress Responses
A progress response always contains a field `retryAfter`, which tells the client how many seconds to wait until the next poll request.
Optionally the response can have the fields `message`, that contains a human user readable text about the current status, and `percent`, that
is a number and shows the progress in percent.
A progress response has always 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 fields of a successful response with data depend on the request.
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 have fields, that contain HTML snippets to provide nice formatting in interactive clients. Those fields are clearly marked by a name that ends with Html, for example, guidanceHtml. There may be related field with the same content in plain text. If such a field exists, it ends with Text as for example, guidanceText.
All HTML fields contain only undangerous formatting tags that can be used without security risks. All tags are filtered by server-side whitelist.
# Group Index
## Index [GET /api/v1]
Note: This is the only web service method that provides a 200 response if no access token was sent.
If an invalid access token was sent, the response is still a 401, though.
+ Request
+ Header
X-Acrolinx-Auth: ""
+ Response 200 (application/json)
{
"data": {
"server": {
"version": "5.1.0.123",
"name": "Acrolinx Core Platform"
},
"locales": [ "en" ]
},
"links": {
"signIn": "https://tenant.acrolinx.cloud/api/v1/auth/sign-ins"
}
}
+ Request
+ Header
X-Acrolinx-Auth: 123579080a8d1fee12490a90dc3
+ Response 200 (application/json)
{
"data": {
"server": {
"version": "5.1.0.123",
"name": "Acrolinx Core Platform"
},
"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": {}
}
## Platform Capabilities [GET /api/v1/capabilities]
An aggregation of the capabilities of the APIs subresources. This resource serves a single entry point for clients that need
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 is handled either with a configured access token, with single sign-on (SSO) or in an interactive process by signing in with the Acrolinx sign-in web page.
Embedded integrations use either the configured access token or SSO.
Interactive clients with a human user use SSO or the interactive process.
## Request/Validate an API Token [POST /api/v1/auth/sign-ins]
The sign-in collection allows Acrolinx API clients to request user authentication and to check
the validity and privileges of existing access tokens.
If the Core Platform is configured for Single Sign-on, 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; 12345
+ Response 200 (application/json)
No sign-in needed, the response body will contain valid access tokens.
The server 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
successful sign-in procedure. 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 supplied.
+ 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 client to acquire the session data:
- `interactive` a link to a website that allows the user to authenticate and
permit the client to access the server. If a language was provided in the
`X-Acrolinx-Client-Locale` header, the link will point to a localized
version of that website 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 duration in seconds, that the `interactive` link will stay valid. If the
Sign-in page was loaded before this time, the server 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 or missing or the user couldn't be created.
+ Header
WWW-Authenticate: ACROLINX_TOKEN, ACROLINX_SIGN_IN (, ACROLINX_SSO)
+ Attributes (object)
+ Response 503
The server 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}]
This resource lets a client wait for a user to authenticate and authorize it to use the
privileged parts of the Acrolinx API. Once the user has completed the sign-in process,
it will return a new access token. It can be sent with each API call to prove the
privileges and identity owned by the user that signed in.
When polling returned a final result, the polling endpoint will disappear and return a `NOT FOUND` status.
+ Request
+ Header
X-Acrolinx-Client: QWxlU2hNyb2bHVnLWlunhQyR29Rm9xpbvZ2lZXRz; 1.0.1.45
+ Parameters
+ id: `99576707-ed8c-44b6-82b8-c3ced8f349d1` (string, required) - poll-id for the authorization request
+ Response 200 (application/json)
A user has completed the sign-in process and the server has 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 clients should pace themselves by respecting the `Retry-After` header.
+ Header
Retry-After: 2
+ Attributes
+ progress
+ `retryAfter`: 2 (number, required)
+ Response 404 (application/json)
The server has no knowledge of the polling token. If a valid poll URI was used, the cause for this 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 just 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]
The new checking API replaces writing guides and Content Profiles with a flat list of guidance profiles. Each guidance profile corresponds to a
writing guide or a Checking Profile. If Sublanguages are activated, they're folded into the list of guidance profiles.
For each guidance profile, the server provides information about the language, activated goals, and term sets. The client may use this
for filtering purposes, but they can only select one (complete) guidance profile for checking (for example, not deselect goals).
+ Response 200 (application/json)
{
"data": {
"guidanceProfiles": [
{
"id": "aud-1",
"displayName": "Tom the Technical Type",
"language": {
"id": "en-gb",
"displayName": "English (Great Britain)"
},
"goals": [{
"id": "spelling",
"displayName": "Spelling",
"color": "#f21"
},
{
"id": "voice.readability",
"displayName": "Clarity",
"color": "#f22"
},
{
"id": "term.unsuitable",
"displayName": "Unsuitable Term",
"color": "#f23"
},
{
"id": "term.admitted",
"displayName": "Use with caution",
"color": "#f24"
}],
"termSets": [{
"displayName": "Switches"
},
{
"displayName": "Acrolinx"
}]
},
{
"id": "aud-2",
"displayName": "Randolf Redakteur",
"language": {
"id": "de",
"displayName": "German"
},
"goals": [{
"id": "spelling",
"displayName": "Spelling",
"color": "#f21"
}],
"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 uploading the document it will be scheduled for analysis. Once Acrolinx is done checking the document
all results will be collected and made available. This leads to the following steps when using the check API:
* submit a check
* poll for progress
* download check results
For an overview on what documents and file types are supported by Acrolinx please consult the list of
[Supported Input Types](https://docs.acrolinx.com/coreplatform/latest/en/compatibility/supported-input-types).
The same information is available in the checking capabilities.
This call includes an implicit "create/search for document" (in case no document id was given) and "update document" (in case document id was given).
+ Request (application/json)
A minimal request declaring the format only:
{
"content": "text to check", // required
"checkOptions": {
"contentFormat": "markdown", // optional, default: auto
},
}
A minimal request using a document reference to tell the format:
{
"content": "text to check", // required
"document": { // optional, default: empty "document" object
"reference": "C:\\abc.md", // optional, default: do not search for ID, always create
}
}
If a standard format is configured on the server, 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
"reportTypes": ["scorecard"], // optional, default: scorecard
"contentFormat": "markdown", // optional, default: auto
"checkType": "batch", // optional, default: interactive
// the use case of the check, can be:
// interactive = human user checks own document
// batch = human user checks many own documents
// baseline = a repository of documents is checked, the user doesn't own the documents
// automated = check of a single document for automated scenarios as for example a git hook
"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 client known id hint e.g. a file name
"customFields": [ // optional
{
"key": "field1",
"value": "value1"
},{
"key": "field2",
"value": "value2"
}
]
}
}
+ 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 How-To
#### Ignore All Issue Occurrences
Every issue in the check result has the attribute `positionalInformation.hashes.issue`. You can use this attribute to find all occurrences of an issue. All these issues can be ignored together.
The integration can also remember the `positionalInformation.hashes.issue` attribute after an ignore-all operation. This 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`. You can 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 it can't be replaced with a replace-all operation.
Note that not all occurrences of an issue always have the same suggestions. In this case, the replace-all operation only applies to issues with the same suggestion.
### Poll Check Result [GET]
Polls the check result. Either a progress or the completed result is returned. The URL for the request is found in the submitted check's "result" link.
+ Parameters
+ id: `AB-153` (required, string) ... the check id
+ 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 are contained in the response depends on configuration, request and the 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": 57,
"status": "red",
"scoresByStrategy": [
{
"id": "average",
"score": 100
},
{
"id": "minimum",
"score": 100
}],
"scoresByGoal": [
{
"id": "GRAMMAR",
"score": 100
},
{
"id": "STYLE",
"score": 100
},
{
"id": "TERMINOLOGY",
"score": 100
},
{
"id": "INFORMALITY",
"score": 100
},
{
"id": "READABILITY",
"score": 100
},
{
"id": "SPELLING",
"score": 100
},
{
"id": "TERMINOLOGY_ADMITTED",
"score": 0
}],
"metrics": [
{
"id": "Clarity index",
"score": 100
},
{
"id": "Informality index",
"score": 47
},
{
"id": "Liveliness index",
"score": 50
},
{
"id": "Flesch Reading Ease",
"score": 36
}]
},
"counts": {
"sentences": 10,
"words": 121,
"issues": 15
},
"goals": [
{
"id": "SPELLING",
"displayName": "Spelling",
"color": "#ff838b",
"issues": 0
},
{
"id": "GRAMMAR",
"displayName": "Grammar",
"color": "#97beff",
"issues": 0
},
{
"id": "STYLE",
"displayName": "Style",
"color": "#70cb9c",
"issues": 0
},
{
"id": "TERMINOLOGY",
"displayName": "Deprecated Terms",
"color": "#ffc0ff",
"issues": 0
},
{
"id": "TERMINOLOGY_ADMITTED",
"displayName": "Admitted Terms",
"color": "#90b0fd",
"issues": 0
},
{
"id": "READABILITY",
"displayName": "Clarity",
"color": "#b77891",
"issues": 0
},
{
"id": "INFORMALITY",
"displayName": "Conversational Tone",
"color": "#cb3393",
"issues": 0
}],
"issues": [
{
"goalId": "spelling",
"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,
"positionalInformation": {
"hashes": {
"issue": "BhKh3iaGBjB7Cw6M/GwrLQ==",
"environment": "vJ9eCVViEpIdM76h+5K/nA==",
"index": "hjlRLT0K+LlvlslKdNUlhw==1"
},
"matches": [{
"extractedPart": "zen", # DRAFT
"extractedBegin": 30,
"extractedEnd": 33,
"originalPart": "zen",
"originalBegin": 19247,
"originalEnd": 19255
}, {
"extractedPart": "te", # DRAFT
"extractedBegin": 33,
"extractedEnd": 35,
"originalPart": "&te;",
"originalBegin": 19250,
"originalEnd": 19254
},{
"extractedPart": "nse", # DRAFT
"extractedBegin": 35,
"extractedEnd": 38,
"originalPart": "nse",
"originalBegin": 19254,
"originalEnd": 19257
}]
},
"readOnly": true,
"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": "term.unsuitable",
"internalName": "term_flag",
"displayName": "<b>Illegal sublanguage variant</b> of preferred term",
"guidance": "<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",
"displaySurface": "Please",
"positionalInformation": {
"hashes": {
"issue": "3qyt/AVxwNTOUQSuMA7brw==",
"environment": "TiwIFBwA6X920mDAezJTyQ==",
"index": "Lm9PqBGGm+tj21rt3pkpjA==1"
},
"matches": [{
"extractedPart": "Please", # DRAFT
"extractedBegin": 766,
"extractedEnd": 772,
"originalPart": "Please",
"originalBegin": 28223,
"originalEnd": 28229,
}],
},
"readOnly": false,
"issueLocations": [],
"suggestions": [
{
"surface": "blablub",
"icon": "https://tenant.acrolinx.cloud/tng/icons/preferred.svg",
"groupId": "2653",
"replacements": ["blablub" ]
}
}
],
# DRAFT ------START------
"debug": {
"term": {
"surface": "please",
"status": "DEPRECATED",
"termSets": ["RA-Terms"],
"domains": ["RA-Terms"],
"variant": "legalVariantIllegal",
}
}
# DRAFT -------END-------
},
{
"goalId": "voice.readability",
"internalName": "en-clarity-medium",
"displayName": "Too complex? Your readers need a medium level of clarity. ",
"guidance": "",
"displaySurface": "Reports ... length",
"positionalInformation": {
"hashes": {
"issue": "E3OxJ3bFcfWLyAisUxufAA==",
"environment": "XVYQZVyCoFOr1TDeyXuMgg==",
"index": "accsS0dbn/3rafcbT9NJGw==1"
},
"matches": [{
"extractedPart": "Reports", # DRAFT
"extractedBegin": 1360,
"extractedEnd": 1367,
"originalPart": "Reports",
"originalBegin": 33173,
"originalEnd": 33180,
}, {
"extractedPart": "length", # DRAFT
"extractedBegin": 1749,