Documentation
Operating instructions
Deployed engines (live)
Read just now from GET https://gateway-staging-d9e1dbd7.up.railway.app/v1/engines. Every receipt carries the same provenance.
| engine | ape |
|---|---|
| upstream repo | https://github.com/Attempto/APE |
| commit | 5f4d5354a45fb772763bf1a9543f508f15b28982 |
| vendored source sha256 | aad00afd5613a72432b88207e92e174cf42be19c1a33058d28d58696cd5cbb1e |
| runtime | SWI-Prolog 9.2.9 |
| image digest | sha256:b2a10417ae125a4e8406b292aea0b57a8b504aa3603fd72589e90240cde79dbb |
| lexicon | clex · https://github.com/Attempto/Clex @ 20960a5ce077 |
| lexicon sha256 | 2996fabfe0cf5a402b9ff7d76e09cb6e2fbedda51e917367c0b9f81fde6266ec |
| built at | 2026-11-18T14:52:27Z |
| engine | gf |
|---|---|
| upstream repo | https://github.com/Attempto/ACE-in-GF |
| commit | 92ef598db5dda9b75aa0e7fae1ed4eb2f8303f5b |
| vendored source sha256 | 6e0ec3b9e077fb64e85b988f35fe175b6117ce828ca181201052a9e615b77e7a |
| runtime | GF 3.12.0; RGL 20260403 |
| image digest | sha256:0f1a56239471ff327b2ccee9e0effe0bd1060b24f5bb7cf510ca9df3c55e8d9f |
| lexicon | clex · https://github.com/Attempto/Clex @ 20960a5ce077 |
| lexicon sha256 | 45d3f35bbc93b6a62293214d49a625ddc887bdba7e1359005bad31f1a5252c1b |
| grammar | ace+clex · concrete ClexAce |
| built at | 2026-11-18T15:10:36Z |
| engine | gf |
|---|---|
| upstream repo | https://github.com/Attempto/ACE-in-GF |
| commit | 92ef598db5dda9b75aa0e7fae1ed4eb2f8303f5b |
| vendored source sha256 | 6e0ec3b9e077fb64e85b988f35fe175b6117ce828ca181201052a9e615b77e7a |
| runtime | GF 3.12.0; RGL 20260403 |
| image digest | sha256:ee0fee24093c94c2b739243900157754fb3ac61b855125bc1e8e65092d44e8de |
| lexicon | words300 · https://github.com/Attempto/ACE-in-GF @ 92ef598db5dd |
| lexicon sha256 | 5b7277d064ec73310d7a1f70fbda1b8d08cc51a2f8b09a3b555888e981281638 |
| grammar | acewiki_aceowl+words300 · concrete Words300Ace |
| built at | 2026-11-18T14:11:43Z |
gf_multi languages: Ace Bul Cat Chi Est Fre Gre Hin Ita Mlt Pol Rus Spa Swe Urd
ACE in ten minutes
Attempto Controlled English (ACE) is English with a fixed grammar and a fixed interpretation: every ACE sentence has exactly one meaning, which the parser (APE) writes down as a discourse representation structure and reads back to you as a paraphrase. The paraphrase is the point. A receipt says the text is ACE; only you can say whether its meaning is the one you wanted.
Shape of a sentence
- Simple:
A guest pays a fee.— determiner, noun, verb, object. Every content word must be in the lexicon (Clex) or in youruser_lexicon. - Universal rules:
Every guest that leaves late pays a fee.—every, relative clauses withthat/who/which. - Conditions:
If a guest leaves late then the guest pays a fee.—if … then …; usethe guestto refer back. - Negation and modality:
No guest smokes.,A guest can pay.,It is false that a guest smokes. - Numbers, strings and variables:
A room has 2 beds.,A guest's name is "Ana".,There is a guest X. X waits.
What usually goes wrong
- Unknown lowercase words are errors (
Every xylo waits.); capitalised unknown words are read as proper names, with a warning. - Clock times, dates and units need the ACE forms;
after 11:00is not ACE as written. - Phrasal verbs (
checks out) and plain-English shortcuts are not in the grammar; rephrase (leaves). - Articles before proper names and dangling
thewithout an antecedent change the meaning; read the paraphrase.
The reference material is the Attempto group's documentation: attempto.ifi.uzh.ch/site/docs — the ACE construction rules, interpretation rules and the APE web-service description. The policy applied here is strict-v1: warnings are valid, errors are not, guessing is never used.
ACE Validation API: Operating Instructions
Derived from schemas/openapi.yaml, which governs. Base URL https://gateway-staging-d9e1dbd7.up.railway.app/v1 (Railway-generated domain, D-013. The exact host is in GET /v1/engines docs and on /docs).
Auth header: Authorization: Bearer ace_live_… (create a key at /account).
1. Validate text
curl -s https://gateway-staging-d9e1dbd7.up.railway.app/v1/validate \
-H "Authorization: Bearer $ACE_KEY" -H "Content-Type: application/json" \
-d '{"text":"Every man is a human."}'
Read three fields, in this order:
verdict.ace_valid: is it ACE under the named parser, lexicon and policy?engines.ape.outputs.paraphrase: is this what you meant? Only you can answer that.engines.ape.messages: if invalid, each message givessentence,token,valueand arepairhint.
A 200 with ace_valid: false is a successful validation. The text is simply not ACE.
Request fields
| Field | Type | Default | Notes |
|---|---|---|---|
text | string | (required) | 1–10,000 chars, ≤ 200 sentences |
user_lexicon | string | none | APE lexicon lines, e.g. noun_sg(minibar, minibar, neutr). ≤ 50 KB |
outputs | string[] | ["drs","paraphrase","gf_trees"] | Also: drspp paraphrase1 paraphrase2 syntax tokens owlfss |
visibility | private | link | private | link lets anyone with the id read the receipt |
Adding words
curl -s https://gateway-staging-d9e1dbd7.up.railway.app/v1/validate -H "Authorization: Bearer $ACE_KEY" -H "Content-Type: application/json" \
-d '{"text":"Every mman is a hhuman.","user_lexicon":"noun_sg(mman, mman, masc).\nnoun_sg(hhuman, hhuman, neutr)."}'
(The example is from the APE README.) The receipt then records input.user_lexicon.sha256, so its claim is
"valid under Clex plus this lexicon".
2. Fetch a receipt
GET /v1/receipts/{id}. Private receipts need the creating key.
3. Verify a receipt (no trust in our database needed)
curl -s https://gateway-staging-d9e1dbd7.up.railway.app/v1/receipts/verify -H "Content-Type: application/json" \
-d "{\"receipt\": $(cat receipt.json), \"rerun\": true}"
signature_valid and hash_valid check that the receipt is genuine and unaltered. rerun.same_engines: false means
the deployed engines have changed since the receipt was issued. That is not a failure, but the result can't be compared.
4. Translate (GF subset)
POST /v1/translate {"text":"…","to":["Fre","Swe"]}. Valid language codes: GET /v1/engines → gf_multi.languages.
Works only within the ACE-in-GF subset and its ~300-word multilingual vocabulary. Otherwise 422 gf_not_covered.
5. Errors
| HTTP | error.code | What to do |
|---|---|---|
| 400 | bad_request, text_too_long, too_many_sentences, bad_user_lexicon | Fix the request |
| 401 | unauthorized | Check key |
| 404 | not_found | Wrong id, or a private receipt |
| 422 | gf_not_covered, unknown_language | Translation only |
| 429 | rate_limited | Wait Retry-After seconds |
| 503 | engine_busy, engine_timeout, engine_unavailable | Retry. For timeout, split the text |
No receipt is ever issued with a 4xx/5xx.
6. CI (GitHub Action)
- uses: benmikeal/ace-api/action@v1
with:
files: 'rules/**/*.ace'
api-key: ${{ secrets.ACE_KEY }}
Fails the job if any file has ace_valid: false, annotates the offending token, and writes ace-receipts.json.
Notices
This service runs the Attempto Parsing Engine (APE), © Attempto Group, University of Zurich, licensed under the GNU Lesser General Public License 3.0 (upstream Attempto/APE), with the Clex lexicon, derived from COMLEX, licensed under the GNU General Public License 3.0 (upstream Attempto/Clex), and ACE-in-GF (Attempto/ACE-in-GF) on the Grammatical Framework and its Resource Grammar Library. The engines are used as network services; their exact upstream commits, the hashes of the vendored sources as built and the lexicon hashes are in every receipt and in the engines table above. A receipt certifies only that text parses as ACE under those engines: not that a rule is correct, that its paraphrase matches the author's intent, or that any system implements it.