CoreGX API

API for running CoreGX geometry programs.

CoreGX

CoreGX program execution

post/run-coregx

Run a CoreGX program

Executes a CoreGX program and returns the CoreGX output (SVG, XML, and/or symbolic measurement results, depending on the requested output flags). Verifies that all constraints can be resolved before producing output. Application-level outcomes (both success and failure) are returned with HTTP status 200; inspect the `ok` field to tell them apart. Only request-routing problems use other status codes (404, 405).

Request body

Field	Type	Description
`program`required	string	The CoreGX program to execute.
`apikey`	string	A valid CoreGX API key, supplied in the request body. Required for external requests; requests originating from the official GenGX site session do not need to provide one.
`seed`	integer	Random seed. Defaults to a random integer if omitted.
`disableOptimization`	boolean	If true, disables point location optimization. Significantly speeds up requests.
`all`	boolean	If true, includes every output type (SVG, XML, app, and equations) and overrides the individual output flags below.
`svg`	boolean	Include SVG output in the response. Ignored when `all` is true.
`dxf`	boolean	Include DXF output in the response. Ignored when `all` is true.
`xml`	boolean	Include XML output in the response. Ignored when `all` is true.
`app`	boolean	Include app output in the response. Ignored when `all` is true.
`equationformats`	object[]	Formats for equation output. The "tex" format generates expressionTex, valueTex, and valueRealAsTex. Possible values: actionscript, c, contentmathml, cpp, csharp, derive, displaymathml, java, javascript, lua, maple, mathematica, matlab, maxima, mupad, nspire, python, string, tex, vb.
`allformats`	boolean	Include all equation export formats in output. Ignored when `all` is true.

Responses

200The program was processed. On success, `ok` is true and `value` holds the requested output. On failure, `ok` is false and `error` holds a code identifying the cause (see the examples).

Success

Returned when the program executed.

Field	Type	Description
`ok`	boolean	`always true`
`value`	object	The CoreGX output, passed through from the engine. Which fields are present depends on the requested output flags.
`value.svg`	string	SVG output. Present when SVG output was requested.
`value.xml`	string	XML output. Present when XML output was requested.
`value.dxf`	string	ASCII DXF v13 output. Present when DXF output was requested.
`value.equations`	object[]	Symbolic measurement results. Present when equation output was requested.

Error

Returned when the request could not be fulfilled.

Field	Type	Description
`ok`	boolean	`always false`
`error`	string	A code identifying the cause of the failure, or a free-form message (e.g. `Could not parse output: ...` when CoreGX emits unparseable output). Errors in the user-supplied geometry are not reported here; they come back inside the successful `value` payload.

Examples

Success

{
  "ok": true,
  "value": {
    "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\">...</svg>",
    "equations": [
      {
        "expression": "distance(A,C)",
        "expressionTex": "distance(A,C)",
        "valueTex": "5",
        "valueRealAsTex": "5"
      }
    ]
  }
}

Malformed request body, or missing program

{
  "ok": false,
  "error": "invalid-request-format"
}

Missing or unknown API key

{
  "ok": false,
  "error": "invalid-coregx-api-key"
}

API key has no remaining CoreGX credits

{
  "ok": false,
  "error": "not-enough-coregx-credits"
}

Too many requests from your IP in flight at once

{
  "ok": false,
  "error": "concurrent-rate-limit"
}

Too many requests from your IP within the last minute

{
  "ok": false,
  "error": "ip-rate-limit"
}

Program exceeded the execution time limit

{
  "ok": false,
  "error": "process-timed-out"
}

The CoreGX engine could not be launched or crashed

{
  "ok": false,
  "error": "server-error"
}

404Endpoint not found, or the request was not routed through an allowed host.

Field	Type	Description
`ok`	boolean	`always false`
`error`	string	A code identifying the cause of the failure, or a free-form message (e.g. `Could not parse output: ...` when CoreGX emits unparseable output). Errors in the user-supplied geometry are not reported here; they come back inside the successful `value` payload.

Examples

{
  "ok": false,
  "error": "location-not-found"
}

405Method not allowed; the endpoint only accepts POST.

Field	Type	Description
`ok`	boolean	`always false`
`error`	string	A code identifying the cause of the failure, or a free-form message (e.g. `Could not parse output: ...` when CoreGX emits unparseable output). Errors in the user-supplied geometry are not reported here; they come back inside the successful `value` payload.

Examples

{
  "ok": false,
  "error": "method-not-allowed"
}

Reference

Reference material for writing CoreGX programs

get/get-syntax

Get the CoreGX syntax guide

Returns the CoreGX syntax guide: a Markdown document describing the CoreGX program language. Takes no parameters and requires no authentication.

Responses

200The syntax guide was returned.

Field	Type	Description
`ok`	boolean	`always true`
`value`	string	The CoreGX syntax guide, as Markdown.

Examples

{
  "ok": true,
  "value": "# CoreGX syntax\n\nA point is declared with..."
}

404Endpoint not found, or the request was not routed through an allowed host.

Field	Type	Description
`ok`	boolean	`always false`
`error`	string	A code identifying the cause of the failure, or a free-form message (e.g. `Could not parse output: ...` when CoreGX emits unparseable output). Errors in the user-supplied geometry are not reported here; they come back inside the successful `value` payload.

Examples

{
  "ok": false,
  "error": "location-not-found"
}

405Method not allowed; the endpoint only accepts GET.

Field	Type	Description
`ok`	boolean	`always false`
`error`	string	A code identifying the cause of the failure, or a free-form message (e.g. `Could not parse output: ...` when CoreGX emits unparseable output). Errors in the user-supplied geometry are not reported here; they come back inside the successful `value` payload.

Examples

{
  "ok": false,
  "error": "method-not-allowed"
}