Skip to content
Facteur for developers

Save a pattern

POST
/v1/inboxes/{id}/extractors
curl --request POST \
  --url https://api.facteur.eu/v1/inboxes/example/extractors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "key": "example", "label": "example", "scope": "text", "pattern": "example" }'

The pattern is compiled by the ingestion engine before it is saved. One that only failed at reception would silently produce nothing, with no way to find out.

key becomes a property name under message.extract, which is why it is constrained to something usable as one.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The inbox identifier — the same string that prefixes its receiving address.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
key
required

Letters, digits and underscores, starting with a letter — it has to be usable as a property name.

string
/^[a-zA-Z][a-zA-Z0-9_]{0,39}$/
label
string
scope
string
default: text
Allowed values: text html subject
pattern
required
string

Responses

Section titled “Responses”

201

Section titled “201”

The extractor.

Media typeapplication/json
object
id
required
string
key
required

The property name this appears under in message.extract.

string
label
required
string
scope
required
string
Allowed values: text html subject
pattern
required
string
createdAt
string format: date-time
Example
{
  "scope": "text"
}

400

Section titled “400”

INVALID_KEY, PATTERN_REQUIRED, INVALID_PATTERN (the engine says why), or INVALID_JSON.

Media typeapplication/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object
error
required
object
code
required

The stable, machine-readable reason.

string
message

A sentence for whoever is reading the failure. Not part of the contract.

string
Example
{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}

401

Section titled “401”

No usable credential. UNAUTHENTICATED when none was presented, KEY_UNKNOWN, KEY_REVOKED or KEY_EXPIRED when a key was — kept distinct on purpose, because “mint a new one” and “somebody took this away from you” are different facts to whoever is reading a red pipeline.

Media typeapplication/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object
error
required
object
code
required

The stable, machine-readable reason.

string
message

A sentence for whoever is reading the failure. Not part of the contract.

string
Example
{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}

403

Section titled “403”

SCOPE_INSUFFICIENT (the message names the scope this request wanted and the ones the key holds), KEY_CANNOT_REACH (no scope opens this route to a key at all), FORBIDDEN, or one of the stated refusals listed under x-api-key-refusals.

Media typeapplication/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object
error
required
object
code
required

The stable, machine-readable reason.

string
message

A sentence for whoever is reading the failure. Not part of the contract.

string
Example
{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}

404

Section titled “404”

INBOX_NOT_FOUND. An inbox in a workspace the key does not reach answers the same way as one that does not exist — telling the two apart would let anyone map a colleague’s workspaces one request at a time.

Media typeapplication/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object
error
required
object
code
required

The stable, machine-readable reason.

string
message

A sentence for whoever is reading the failure. Not part of the contract.

string
Example
{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}

409

Section titled “409”

KEY_ALREADY_USED — this inbox already has an extractor under that key.

Media typeapplication/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object
error
required
object
code
required

The stable, machine-readable reason.

string
message

A sentence for whoever is reading the failure. Not part of the contract.

string
Example
{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}