Add an AI provider, or find the one already added, by external identifier

The body is the full representation: null clears a field, an absent field is left alone. Answers 201 when the row was created and 200 when it was updated, which is how a system of record tells a create from a reconcile.

Quire permissions

Required capability: ai/configure.

Credential scopes: integrations:write.

The acting subject must also be allowed to perform this action in the organisation.

PUT

https://your-organisation.quirelms.com/api/v1/ai_providers/ext:{external_id}

View as Markdown

Authorisation

apiKeyoptionalHTTP
oauth2optionalOAuth 2.0

Path parameters

external_idstringrequired
The external identifier, unique per tenant per type, as supplied by the system of record.

Header parameters

Quire-Versionoptionalstring
The dated API revision to serve this request at. Omitted, the request is served at the revision the credential was issued against. The response echoes the revision actually applied.

format: date
Idempotency-Keyoptionalstring
A caller-chosen key making this request safe to retry. A replay of a completed request returns the recorded response with Idempotency-Replayed: true. Reusing a key for a different request is refused.

maxLength: 255

Request bodyJSONrequired

provideropenaiorazure_openaioranthropicorgeminiorbedrockordeepseek+3 morerequired
labelstringrequired
maxLength: 120, minLength: 1
regionstringrequired
Must be the organisation's data region.

maxLength: 20, minLength: 2
training_opt_outlocalorcontractualorconfiguredorunverifiedrequired
endpointoptionalstringornull
Absent for a hosted vendor with a fixed address and for the built-in demonstration model.
2 variants
One of the following:
string
null
credentialoptionalstringornull
The provider API key. Write-only: it is sealed on receipt and never returned, logged or shown again.
2 variants
One of the following:
string
null
modelsoptionalarray ofstring
maxLength: 200, minLength: 1
agreement_referenceoptionalstringornull
2 variants
One of the following:
string
null
acknowledge_unverifiedoptionalboolean

Returns

200

Success.

JSON

idstringrequired
external_idstring | nullrequired
providerstringrequired
labelstringrequired
regionstringrequired
key_originstringrequired
training_opt_outstringrequired
allowed_modelsarray ofstringrequired
capabilities_snapshotunknownrequired
statusstringrequired
acknowledged_atstringornullrequired
2 variants
One of the following:
string
null
validated_atstringornullrequired
2 variants
One of the following:
string
null
created_atstringrequired
RFC 3339 timestamp in UTC.
updated_atstringrequired
RFC 3339 timestamp in UTC.

201

Success.

JSON

idstringrequired
external_idstring | nullrequired
providerstringrequired
labelstringrequired
regionstringrequired
key_originstringrequired
training_opt_outstringrequired
allowed_modelsarray ofstringrequired
capabilities_snapshotunknownrequired
statusstringrequired
acknowledged_atstringornullrequired
2 variants
One of the following:
string
null
validated_atstringornullrequired
2 variants
One of the following:
string
null
created_atstringrequired
RFC 3339 timestamp in UTC.
updated_atstringrequired
RFC 3339 timestamp in UTC.

401

The credential is missing, malformed, expired or revoked.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

403

The credential lacks the scope this operation requires, or the acting subject lacks the capability.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

404

No such resource, or none this credential is permitted to know about.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

409

The request conflicts with the current state, with a previous use of the same idempotency key, or with a concurrent write.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

422

The request was understood and its content is not valid. errors names each field.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

429

A rate limit or a concurrency cap was reached. Retry-After says when to try again.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

500

Something failed at our end. Quote request_id when reporting it.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null