Connect your own API

Gather your API details

Finish your Artie account setup before connecting. Have your API's address, authentication details and operation definitions ready.

• Use a public HTTPS base URL without embedded credentials. Requests use port 443 and don't follow redirects.
• Authentication can be a header API key, a bearer token or no authentication. API OAuth and browser sign-in aren't supported.
• Supply an OpenAPI 3.0 or 3.1 definition in JSON or YAML, manually entered REST operations, or fixed GraphQL queries or mutations.

Setup prepares the connection without making a test call to your API. Connecting doesn't confirm that the key works or that the API will accept a request.

Enter the connection and operations

Open Apps and start an API connection. You can give it an optional app name to help you recognize it later.

1. Supply an OpenAPI definition by uploading a file, pasting it or entering a public definition URL. The definition URL is fetched without your API key.
2. For another definition type, open Advanced and choose REST operations or GraphQL under API type.
3. For REST operations, enter the method, path, typed query parameters and any optional JSON body. Use placeholders such as {orderId} for path inputs. For GraphQL, enter fixed queries or mutations; their variables become the inputs.
4. Enter the base URL. With OpenAPI, the definition's base URL is used unless you enter an override in Advanced.
5. Check the authentication settings in Advanced and enter the required key or token, or choose no authentication. Choose who can use the connection.
6. Select Review connection. If fields are highlighted, correct them and try again.

For an order lookup, you might use the base URL https://api.example.com and define GET /orders/{orderId}. Artie supplies the orderId when it uses that operation.

Review what Artie can use

The review shows the API address and groups the prepared operations by how they'll run.

1. Check the API address and both operation groups. Open Request details to inspect the request paths and descriptions.
2. If operations were skipped, read the displayed reasons. Use Back to correct the definition or connection details, then review again. If authentication requires a key, enter it again.
3. Select Connect when the prepared operations match what you want Artie to use.

• Runs without asking: operations Artie can use without requesting approval.
• Asks first: operations that require approval before they run.
• Operations that can't be used: expand this group to see the requests and their reasons.

Some definition features, including recursive or external references, are skipped. A definition update can change which operations are available.

Use the connected API

After connecting, ask Artie for work that uses one of the defined operations. Artie can use these operations as connected-app tools in Slack, web chat and calls. Operations in Asks first wait for approval before running.

“Use the Order service API to look up order ORD-1042 and summarize its current status.”

API requests aren't automatically retried. If a write has an unknown outcome, check the API's records before asking Artie to repeat it.

Update operations or replace a credential

Open the API connection's settings in Apps. Management controls are available only if you have permission to manage the connection.

If saving fails, correct the highlighted fields or follow the displayed error and try saving again.

1. To change the operations, select Update operations and supply the new definition or operation entries.
2. Select Save operations. When it succeeds, you'll see Operations updated. Check the resulting operation list.
3. To replace a key or token, select Replace credential. For a connection with no authentication, select Change connection.
4. Enter the new authentication details. If you're changing the base URL or credential header, make that change here together with the new credential.
5. Select Save connection. For a saved credential, you'll see Saved. Artie will use the new credential from now on. For no authentication, you'll see Connection updated.

Saving a definition applies it immediately, without a separate review screen. Changed operations lose their previous approvals; unchanged operations keep them. If the API rejects the key with a 401 response, replace the credential in Apps.

Disconnect or connect again

Disconnect the API from Apps when Artie should stop using its operations. After disconnecting, those operations can no longer run.

To connect it again, return to Apps and repeat setup and review. Saved settings can be reused, but the old key isn't filled in. Supply the key again if the API requires one. Custom API connections are reconnected from Apps rather than a connect card in chat.