arText API documentation

post/v1/reports

Create an analysis report

Validates and queues text. The 202 response identifies status and event resources; it does not mean analysis is complete.

Authorization: Bearer ARTEXT_API_KEY

Parameters

Idempotency-Keyheader

Recommended unique key for safely retrying this creation request. It is scoped to the authenticated caller, retained for 24 hours, and must not be reused with a different payload.

Request body

application/json

{
  "$ref": "#/components/schemas/ReportRequest"
}

Create a report

{
  "domain_slug": "plain-language",
  "external_id": "document-123",
  "language": "en",
  "text": "The application will be reviewed at the present time.",
  "text_type_slug": "legal-administrative-text-addressed-to-citizens"
}

Responses

202Successful Response

LocationCanonical status resource for the accepted report.Retry-AfterMinimum number of seconds before the first status poll.X-Request-IDIdentifier to retain for support and tracing.

application/json

{
  "$ref": "#/components/schemas/ReportAccepted"
}

Report accepted and queued

{
  "events_url": "/v1/reports/rep_7f12a4c8/events",
  "external_id": "document-123",
  "report_id": "rep_7f12a4c8",
  "status": "queued",
  "status_url": "/v1/reports/rep_7f12a4c8"
}

401Missing, invalid, inactive or revoked API key.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

409Idempotency-Key was reused with a different payload.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

413Text exceeds the configured word limit.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

422Request validation failed, including an unknown domain_slug/text_type_slug pair.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

429Rate limit exceeded.

X-Request-IDIdentifier to retain for support and tracing.Retry-AfterSeconds to wait before a retry can be attempted.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

503The analysis queue is unavailable.

X-Request-IDIdentifier to retain for support and tracing.Retry-AfterSeconds to wait before a retry can be attempted.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

get/v1/reports/{report_id}

Retrieve status and results

Returns current state. Honor Retry-After while queued/running; completed and failed are terminal.

Authorization: Bearer ARTEXT_API_KEY

Parameters

report_idpath · required

Unique report identifier returned by POST /v1/reports.

Responses

200Successful Response

Retry-AfterPresent for queued/running reports; wait at least this many seconds before polling again.X-Request-IDIdentifier to retain for support and tracing.

application/json

{
  "$ref": "#/components/schemas/Report"
}

Report queued

{
  "events_url": "/v1/reports/rep_7f12a4c8/events",
  "external_id": "document-123",
  "report_id": "rep_7f12a4c8",
  "status": "queued",
  "status_url": "/v1/reports/rep_7f12a4c8"
}

Report completed

{
  "error": null,
  "external_id": "document-123",
  "position_in_queue": null,
  "report_id": "rep_7f12a4c8",
  "result": {
    "genre": {
      "domain": {
        "name": "Plain language",
        "slug": "plain-language"
      },
      "text_type": {
        "name": "Legal-administrative text addressed to citizens",
        "slug": "legal-administrative-text-addressed-to-citizens"
      }
    },
    "language": "en",
    "measurements": [
      {
        "implementation_version": "1.0",
        "metric_id": "word-count",
        "unit": "words",
        "value": 12
      }
    ],
    "offset_unit": "unicode_code_points",
    "schema_version": "1.0",
    "suggestions": [
      {
        "category": "lexical",
        "explanation": null,
        "id": "sug_1",
        "implementation_version": "1.0",
        "metric_id": "redundant-expressions",
        "metric_title": "Removal of redundant expressions",
        "occurrences": [
          {
            "alternatives": [],
            "edits": [
              {
                "end": 19,
                "start": 0,
                "text": ""
              }
            ],
            "end": 19,
            "id": "occ_1",
            "paragraph_index": 0,
            "replacement": null,
            "sentence_index": 0,
            "start": 0,
            "text": "at the present time"
          }
        ],
        "recommendations": [
          "Remove the expression when the context allows it."
        ],
        "severity": "warning",
        "summary": "Consider expressing this fragment more directly."
      }
    ]
  },
  "status": "completed"
}

Report failed

{
  "error": {
    "code": "analysis_failed",
    "message": "The analysis could not be completed."
  },
  "external_id": "document-123",
  "position_in_queue": null,
  "report_id": "rep_7f12a4c8",
  "result": null,
  "status": "failed"
}

401Missing, invalid, inactive or revoked API key.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

404Report not found.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

429Status rate limit or minimum polling interval exceeded.

X-Request-IDIdentifier to retain for support and tracing.Retry-AfterSeconds to wait before a retry can be attempted.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

503Request protection is temporarily unavailable.

X-Request-IDIdentifier to retain for support and tracing.Retry-AfterSeconds to wait before a retry can be attempted.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

422Validation Error

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

get/v1/reports/{report_id}/events

Stream transitions over SSE

Optional SSE channel for the initial state, changes and heartbeats. It closes on a terminal state; polling remains the supported fallback.

Authorization: Bearer ARTEXT_API_KEY

Parameters

report_idpath · required

Unique report identifier returned by POST /v1/reports.

Responses

200SSE status stream.

X-Request-IDIdentifier to retain for support and tracing.

text/event-stream

{
  "type": "string"
}

A stream closes after completed or failed

"event: status\\ndata: {\"report_id\":\"rep_7f12a4c8\",\"status\":\"running\",\"updated_at\":\"2026-07-15T10:00:02Z\"}\\n\\nevent: status\\ndata: {\"report_id\":\"rep_7f12a4c8\",\"status\":\"completed\",\"updated_at\":\"2026-07-15T10:00:06Z\"}\\n\\n"

401Unauthorized

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

404Not Found

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

429Too Many Requests

X-Request-IDIdentifier to retain for support and tracing.Retry-AfterSeconds to wait before a retry can be attempted.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

503Service Unavailable

X-Request-IDIdentifier to retain for support and tracing.Retry-AfterSeconds to wait before a retry can be attempted.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

422Validation Error

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

get/v1/metrics

List metric implementations

Returns measurement and suggestion implementations, including inactive variants and localized documentation. Narrowing the request to a genre reports which metrics that genre actually evaluates.

Authorization: Bearer ARTEXT_API_KEY

Parameters

analysis_languagequery

Language implementation to return: es, ca or en.

documentation_languagequery

Language used for titles and documentation: es, ca or en.

kindquery

Filter by measurement or suggestion.

enabledquery

Filter by the current implementation status.

domain_slugquery

Text domain of a genre, as listed by GET /v1/text-types.

text_type_slugquery

Text type (genre) inside domain_slug, as listed by GET /v1/text-types.

Responses

200Metric implementations and their documentation.

X-Request-IDIdentifier to retain for support and tracing.

application/json

{
  "$ref": "#/components/schemas/MetricCatalog"
}

401Missing, invalid, inactive or revoked API key.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

422Incomplete or unknown genre filter.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

get/v1/metrics/{metric_id}

Get one metric implementation

Returns the status, category and localized documentation for one language variant, optionally narrowed to a genre.

Authorization: Bearer ARTEXT_API_KEY

Parameters

metric_idpath · required

Stable conceptual metric identifier.

analysis_languagequery · required

Language implementation to return: es, ca or en.

documentation_languagequery

Language used for titles and documentation: es, ca or en.

domain_slugquery

Text domain of a genre, as listed by GET /v1/text-types.

text_type_slugquery

Text type (genre) inside domain_slug, as listed by GET /v1/text-types.

Responses

200Successful Response

X-Request-IDIdentifier to retain for support and tracing.

application/json

{
  "$ref": "#/components/schemas/Metric"
}

401Missing, invalid, inactive or revoked API key.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

404Metric implementation not found.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

422Incomplete or unknown genre filter.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

get/v1/text-types

List text domains and genres

Returns the domains (ámbitos) and the genres (text types) available for a language. The slug pair of a genre is what POST /v1/reports expects.

Authorization: Bearer ARTEXT_API_KEY

Parameters

languagequery

Catalog language: es, ca or en.

Responses

200Editorial catalog for the requested language.

X-Request-IDIdentifier to retain for support and tracing.

application/json

{
  "$ref": "#/components/schemas/PublicTextTypeCatalog"
}

401Missing, invalid, inactive or revoked API key.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

422Unsupported language.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

get/v1/text-types/{domain_slug}/{text_type_slug}

Get one genre

Returns the sections and contents recommended for a genre, plus the exact report_defaults to forward to POST /v1/reports.

Authorization: Bearer ARTEXT_API_KEY

Parameters

domain_slugpath · required

Text domain of a genre, as listed by GET /v1/text-types.

text_type_slugpath · required

Text type (genre) inside domain_slug, as listed by GET /v1/text-types.

languagequery

Catalog language: es, ca or en.

Responses

200Genre detail and its report defaults.

X-Request-IDIdentifier to retain for support and tracing.

application/json

{
  "$ref": "#/components/schemas/PublicTextTypeDetail"
}

401Missing, invalid, inactive or revoked API key.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

404Genre not found for this language.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}

422Unsupported language.

X-Request-IDIdentifier to retain for support and tracing.

application/problem+json

{
  "$ref": "#/components/schemas/ApiProblem"
}