NAV Navbar
shell

Introduction

Welcome to the Astui API.

Authentication

To authorize, use this code:

curl "api_endpoint_here"
    -F api_token=your_api_token_here \

Make sure to replace your_api_token_here with your API token.

Astui expects an API token to be contained in the body of every request, any requests without an API token will be refused.

An API token is linked to an individual account, if you are building a plugin then you should request the end users API token and send that with any requests. Do not share your API tokens in publicly accessible locations such as GitHub, client side code, etc.

Authentication Check

You can check an API token a user has entered is valid by making a request against the /validate end point. Please note that this end point is strictly rate limited to prevent abuse.

This is optional, but useful when a user is entering their API token for the first time.

HTTP Request

POST https://astui.tech/api/v1/validate

Query Parameters

Parameter Type Required Description
api_token string true Users API token

Return

The API will return one of four responses in normal circumstances:

Response Message Explanation
200 Authenticated Everything looks good
401 Unauthenticated Invalid token
402 Subscription Required Account currently has no subscription (or active trial)
429 Too Many Attempts Rate limit on token checking reached, see Rate Limit section for details

Headers

Certain meta information can be passed both ways via headers.

Request Headers

When making requests you may find the following useful;

User-Agent

Depending on the framework you are building within you may want to set or override the User-Agent you are passing, this will be logged along with the request and may make trouble shooting easier for both developer and end user.

For example, if you were writing a plugin for WordPress you may want to set the User-Agent to My Amazing Wordpress Plugin v0.0.1 which would then override the default set via whichever request framework you are using such as cURL.

Accept

Setting the Accept header to application/json will force the API to return JSON responses to all requests, in certain circumstances without this you may be sent to the login page and skip the API entirely. This may change in future API versions.

Returned Headers & Rate Limiting

The headers returned currently contain rate limit information which you may want to make use of in your application.

X-RateLimit-Limit

This contains the current rate limit on the API in requests per minute.

X-RateLimit-Remaining

The remaining requests you can make before the reset.

X-RateLimit-Reset

If you reach the rate limit then you will be returned an additional header which contains a unix timestamp telling you when the rate limit will be reset.

Boolean

Boolean

curl -X POST 
  https://astui.tech/api/v1/boolean 
  -F api_token=your_api_token
  -F 'paths[0]=M20.001,20.001L30,30L0,30Z' 
  -F 'paths[1]=M 0 0 L 441 0 L 441 330 L 0 330 L 0 0 Z' # OR
  -F 'paths=["M20.001,20.001L30,30L0,30Z","M 0 0 L 441 0 L 441 330 L 0 330 L 0 0 Z"]'
  -F 'operation=union'

This end point will perform one of four types of Boolean ("Pathfinder") operations on two or more paths and return a path.

Before

After - Unit

Before

After - Intersection

Before

After - Subtraction

Before

After - Exclusive Or

Download Examples

HTTP Request

POST https://astui.tech/api/v1/boolean

Query Parameters

Parameter Type Required Description
paths array true Array of SVG paths to run the operations on, will be run sequentially.
operation string true "union", "intersection", "subtraction", or "exclusive_or"

Return

This end point will return a json object

{"path": "formatted_path_data"}

Brushes

Calligraphic Brush

curl -X POST 
  https://astui.tech/api/v1/calligraphic 
  -F api_token=your_api_token
  -F 'path=M20.001,20.001L30,30L0,30Z' 
  -F 'roundness=0.5'
  -F 'angle=45'
  -F 'width=10'
  -F 'looseness=5'

This end point will apply a calligraphic brush to a path.

Before

After

Download Examples

HTTP Request

POST https://astui.tech/api/v1/calligraphic

Query Parameters

Parameter Type Required Description
path string true SVG Path to run the operation on
roundness numeric true Brush ellipticity. 0.0 to 1.0 - 1.0 being round.
angle numeric true Tilt angle, in degrees
width numeric true Brush width
looseness numeric false Maximum error in pixels allowed for path fitting, if not provided it will be 1

Return

This end point will return a json object

{"path": "formatted_path_data"}

Brush

curl -X POST 
  https://astui.tech/api/v1/brush 
  -F api_token=your_api_token
  -F 'path=M20.001,20.001L30,30L0,30Z' 
  -F 'brush=M20.001,20.001L30,30L0,30Z'

This end point will use the given brush SVG path as a brush for the provided path.

HTTP Request

POST https://astui.tech/api/v1/brush

Query Parameters

Parameter Type Required Description
path string true SVG Path to run the operation on
brush string true SVG Path to use as the brush

Return

This end point will return a json object

{"path": "formatted_path_data"}

Cleanup

Cleanup

curl -X POST 
  https://astui.tech/api/v1/cleanup 
  -F api_token=your_api_token
  -F 'path=M20.001,20.001L30,30L0,30Z' \
  -F 'nice_lines=true' \
  -F 'cut_cusps=true' \
  -F 'cut_loops=true' \
  -F 'loop_intersections=true' \
  -F 'remove_redundant=true' \
  -F 'remove_unneeded=true' \
  -F 'remove_small_handles=true' \
  -F 'fix_lines=true' \
  -F 'remove_small_segments=true' \
  -F 'smooth_corners=true' \
  -F 'axis_align=true' \


This end point will perform the given cleanup operations on a path.

HTTP Request

POST https://astui.tech/api/v1/cleanup

Query Parameters

Parameter Type Required Description
path string true SVG path to run the operations on
nice_lines boolean false Arc length paramterise lines
cut_cusps boolean false Cut cusp Beziers at cusp point
cut_loops boolean false Cut looped Beziers at loop midpoint
loop_intersections boolean false Cut looped Beziers at intersection point
remove_redundant boolean false Remove points that are co-incident with each other
remove_unneeded boolean false Remove unnecessary co-linear point and handles
remove_small_handles boolean false Remove small handles
fix_lines boolean false Arc length Make all straight lines double degenerate
remove_small_segments boolean false Remove very small segments
smooth_corners boolean false Make very obtuse corners smooth
axis_align boolean false Axis align near vertical or near horizontal straight lines

Return

This end point will return a json object

{"path": "formatted_path_data"}

Long Shadow

Long Shadow

curl -X POST 
  https://astui.tech/api/v1/longshadow 
  -F api_token=your_api_token
  -F 'path=M20.001,20.001L30,30L0,30Z' \
  -F 'angle=45' \
  -F 'length=20' 

This end point will add a long shadow to a path.

Before

After

Download Examples

HTTP Request

POST https://astui.tech/api/v1/longshadow

Query Parameters

Parameter Type Required Description
path string true SVG path to run the operations on
angle numeric true The angle to cast the shadow
length numeric true The length of the shadow

Return

This end point will return a json object

{"path": "formatted_path_data"}

Move Points to Tangencies

Tangencies

curl -X POST 
  https://astui.tech/api/v1/tangencies 
  -F api_token=your_api_token
  -F 'path=M20.001,20.001L30,30L0,30Z' 
  -F accuracy=5 
  -F angle=45

This endpoint moved points to tangencies.

Before

After

Download Examples

HTTP Request

POST https://astui.tech/api/v1/tangencies

Query Parameters

Parameter Type Required Description
path string true SVG Path to run the operation on
accuracy numeric true Accuracy of the tangencies operation
angle numeric true Angle to move points to

Return

This end point will return a json object

{"path": "formatted_path_data"}

Offset Path

Offset

curl -X POST 
  https://astui.tech/api/v1/offset 
  -F api_token=your_api_token
  -F 'path=M20.001,20.001L30,30L0,30Z' 
  -F 'offset=50' \
  -F 'join_type=mitre' \
  -F 'mitre_limit=1' \
  -F 'open_loop=loops_cut'

This end point will offset a path.

Before

After

Download Examples

HTTP Request

POST https://astui.tech/api/v1/offset

Query Parameters

Parameter Type Required Description
path string true SVG Path to run the operation on
offset numeric true Can be positive or negative, the distance to offset the path. Positive or negative requirement is difficult to predict as it is based on where the path definition starts and finishes.
join_type string false "mitre", "bevel", or "round" - the type of join to apply. Default: "mitre"
mitre_limit numeric false When using mitre joins you can apply a limit to how far the mitres will be drawn, beyond that point they will not be applied.
open_loop string false "loops_cut" or "loops_invert" - further information on this functionality will be available soon.

Return

This end point will return a json object

{"path": "formatted_path_data"}

Path Fitting

Path Fit

curl -X POST 
  https://astui.tech/api/v1/pathfit 
  -F api_token=your_api_token
  -F 'points=[[1,1],[2,2],[3,3],[4,4]]' \ # OR
  -F 'points[0]=[1,1]' \
  -F 'points[1]=[2,2]' \
  -F 'points[2]=[3,3]' \
  -F 'points[3]=[4,4]' \
  -F 'accuracy=2.0' \
  -F 'closed=true' \

This end points takes an array of X,Y coordinates and will return a path.

HTTP Request

POST https://astui.tech/api/v1/pathfit

Query Parameters

Parameter Type Required Description
points array true A well formed JSON array of X,Y coordinates.
accuracy numeric false Accuracy of path fitting.
closed boolean false Option to close the path. Default: false

Return

This end point will return a json object

{"path": "generated_path_data"}

Outline Stroke

Outline

curl -X POST 
  https://astui.tech/api/v1/outline 
  -F api_token=your_api_token
  -F 'path=M20.001,20.001L30,30L0,30Z' 
  -F 'width=10' \
  -F 'join_type=mitre' \
  -F 'cap_type=butt' \
  -F 'mitre_limit=100' \
  -F 'placement=inset' \
  -F 'dashes=[10,10,20,15]' \ # OR
  -F 'dashes[0]=10' \
  -F 'dashes[1]=10' \
  -F 'dashes[2]=20' \
  -F 'dashes[3]=15' \
  -F 'dash_offset=10' 

This end point will outline stroke a path.

Before

After

Download Examples

HTTP Request

POST https://astui.tech/api/v1/outline

Query Parameters

Parameter Type Required Description
path string true SVG Path to run the operation on
width numeric true Width of the stroke to apply
join_type string false "mitre", "bevel", or "round" - the type of join to apply. Default: "mitre"
cap_type string false "butt", "projecting", or "round" - the type of cap to apply to open paths. Default: "butt"
mitre_limit numeric false When using mitre joins you can apply a limit to how far the mitres will be drawn, beyond that point they will not be applied.
placement string false Placement for the outline, can be "centered", "inset" or "outset" - defaults to "centered" if not provided.
dashes array false The dash pattern to apply to the stroke, defined as dash, gap, dash, gap etc.
dash_offset numeric false The offset to start the dash from defined from the start of the path.

Return

This end point will return a json object

{"path": "formatted_path_data"}

Regularise

Regularise

curl -X POST 
  https://astui.tech/api/v1/regularise
  -F api_token=your_api_token
  -F 'path=M20.001,20.001L30,30L0,30Z' 

This end point will regularise a path, merging self-intersecting and overlapping compound elements, returning a path.

Before

After

Download Examples

HTTP Request

POST https://astui.tech/api/v1/regularise

Query Parameters

Parameter Type Required Description
path string true SVG Path to run the operation on

Return

This end point will return a json object

{"path": "formatted_path_data"}

Rounded Corners

Rounded Corners

curl -X POST 
  https://astui.tech/api/v1/rounded 
  -F api_token=your_api_token
  -F 'path=M20.001,20.001L30,30L0,30Z' \
  -F 'radius=10' \
  -F 'indices=[2,4,6]' \ #OR
  -F 'indices[0]=2' \
  -F 'indices[1]=4' \
  -F 'indices[2]=6' \

This end point will round the given corners of a path.

HTTP Request

POST https://astui.tech/api/v1/rounded

Query Parameters

Parameter Type Required Description
path string true SVG Path to run the operation on
radius numeric true Radius to round the given corners
indices array true An array of integers that related to the points along the path that should be rounded

Return

This end point will return a json object

{"path": "formatted_path_data"}

Smart Point Removal (SPR)

SPR

curl -X POST 
  https://astui.tech/api/v1/spr 
  -F api_token=your_api_token 
  -F 'path=M20.001,20.001L30,30L0,30Z' 
  -F tolerance=20 
  -F decimal=1

This endpoint performs smart point removal on a path.

Before

After

Download Examples

HTTP Request

POST https://astui.tech/api/v1/spr

Query Parameters

Parameter Type Required Description
path string true SVG Path to run the operation on
tolerance numeric true Accuracy of the SPR operation
decimal numeric true Decimal accuracy of the SVG path returned

Return

This end point will return a json object

{"path": "formatted_path_data"}

Recipes

Using recipes to chain actions

curl -X POST 
  https://astui.tech/api/v1/brush 
  -F api_token=your_api_token
  -F 'path=M20.001,20.001L30,30L0,30Z' 
  -F 'actions={"calligraphic": { "roundness" : 0.5, "angle": 32, "width": 5 }, "spr": { "tolerance": 20}, "tangencies": { "accuracy": 5, "angle": 90 } }'

This end point provides a way to chain requests together without having to wait for the server response between each action.

The actions provided will be run sequentially on the path.

The following endpoints can be used in recipes:

The actions parameter should be a well formed JSON array that passes the endpoint name, for example tangencies, calligraphic, or spr along with the variables that you would normally pass to that endpoint.

Recipe Example

{
    "calligraphic": { 
        "roundness" : 0.5, 
        "angle": 32, 
        "width": 5 
    }, 
    "spr": { 
        "tolerance": 20
    },
    "tangencies": { 
        "accuracy": 5, 
        "angle": 90 
    }
}

If you wanted to use the Calligraphic brush function, followed by Smart Point Removal, and finally moving the points to Tangencies, you could use the example to the right as your actions parameter.

HTTP Request

POST https://astui.tech/api/v1/recipe

Query Parameters

Parameter Type Required Description
path string true SVG Path to run the operation on
actions string true A well formed JSON array of actions to take, see above for more details

Return

This end point will return a json object

{"path": "formatted_path_data"}

Errors

The Astui API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API token is wrong.
402 Payment Required -- Trial or subscription expired.
403 Forbidden -- You are not allowed to do that.
418 I'm a teapot.
422 Unprocessable Entity -- The body content will provide you with more detailed error reasons
429 Too Many Requests -- You're requesting too many paths! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.