API - Getting Started Guide

Welcome to the Discovery API! This guide walks you through creating an API token and making your first call, so you can start working with your Discovery account programmatically.

Prerequisites

Before you begin, ensure you have:

• A registered account on manage.discoveryapp.io.
• A stable internet connection.
• A basic understanding of REST APIs and how to make HTTP requests.

Which API version should I use?

Not sure which one you're on, or have questions about migrating? Contact [email protected].

Step 1: Log in to Discovery

1. Open your browser and navigate to manage.discoveryapp.io.
2. Enter your email and password to log in. If you don't have an account, click "Sign up" to create one and verify your email address.

Step 2: Access Your Profile

1. Once logged in, click your name at the bottom of the left sidebar (if the sidebar is collapsed, click your profile image).
2. Select My Profile from the menu to open your profile settings.

Step 3: Navigate to the API Tab

1. In your profile settings, click the API tab.
2. This takes you to the API token management page: https://manage.discoveryapp.io/api-tokens.

Step 4: Create a New API Token

1. On the API token management page, click New Token.

2. Enter a Name for your token (e.g., "VendorInvoiceAPI"). This helps you identify the token's purpose later, and you can change the name at any time.
3. Choose the token's Access: Read and write or Read only.*
4. Click Save.

5. Copy the token immediately and store it securely. It is shown only once.

Step 5: Open the API Docs

1. On the API token management page, click Go to Docs and select 2026-07-01. Each version in the menu has a badge: the newest version is marked current, and older versions are marked deprecated. Build new integrations on the version marked current.
2. The API docs list every endpoint, with an interactive Try It panel for sending real requests.

Step 6: Add Your Token in the Try It Panel

1. In the left menu of the API docs, open GatheredVendorInvoiceFiles and click Gathered Vendor Invoice Files Index.
2. In the Auth section of the Try It panel on the right, paste the token you copied in Step 4 into the Token field.

Step 7: Test Your First API Call

1. With Gathered Vendor Invoice Files Index still open (GET /api/2026-07-01/gathered-vendor-invoice-files    ), click Send API Request.

2. Review the response. If the token is valid, you'll see a list of your gathered vendor invoice files.

To call the API from your own code, send your token in an Authorization: Bearer <your token>     header, along with Accept: application/json    , to endpoints under https://manage.discoveryapp.io/api/2026-07-01    . The Request Sample under the Try It panel shows the full request in several languages.

What Your Token Can Do

• Tokens follow your role. An API token acts as the person who created it, so it can only reach what that person's role allows in Discovery. If your role can view Services but not change them, your token can read services but can't create or edit them, even with full access. If your role changes, your tokens change with it on the next request. A token also counts as its creator for authorship rules: for example, it can only edit or delete incident comments that person wrote (unless they're an Admin). Other attempts return 403 Forbidden. See Roles and Permissions.
• Rate limits. The newest API allows up to 1,000 requests per minute per user, and 1,000 per minute across your whole company. V1 and Beta allow 60 requests per minute.
• Deactivated users. If the user who created a token is deactivated, their tokens stop working.

Using the V1 API

V1 uses the same API tokens. To try it:

1. Click Go to Docs and select 2024-01-01 (v1).
2. Click Authorize in the top right corner, paste your token, and confirm.
3. Open an endpoint, such as /api/v1/gathered-vendor-invoice-files    , and click Try it out.

Best Practices for API Token Management

• Keep Your Token Secure: Never share your API token publicly or store it in unsecured locations like public repositories.
• Rotate Tokens Regularly: Periodically generate new tokens and revoke old ones to maintain security.
• Use Descriptive Names: Give your tokens meaningful names to easily track their usage.
• Monitor Usage: Check the API token management page to monitor token activity and revoke any suspicious tokens.

Next Steps

• Explore other endpoints in the API docs to understand the full range of capabilities.
• Integrate the API into your application using your preferred programming language. The API docs describe every endpoint's request and response format.
• If you encounter issues, reach out to support via the Discovery dashboard or email [email protected].

*Read-Only API Tokens

When creating a token, you can set its Access to Read only. A read-only token can fetch data from any Discovery endpoint your role can view, but is blocked from making any changes.

What you can do with a read-only token:

• Retrieve records (locations, services, vendors, invoices, pickups, etc.)
• Search and filter data
• Export information to external tools or dashboards

What you cannot do with a read-only token:

• Create new records (POST)
• Update existing records (PUT or PATCH)
• Delete or archive records (DELETE)

If a read-only token is used to attempt a write operation, the API returns a 403 Forbidden     response.

When to use a read-only token:

Use a read-only token any time you're sharing API access with a third-party reporting tool, a BI dashboard, or a developer who only needs to pull data. It limits the blast radius if the token is ever exposed — an attacker with a read-only token can't modify or delete your data.

Note: Like all tokens, a read-only token is displayed only once at the time of creation. Copy it to a secure location before closing the dialog.

If you have additional questions or need more in depth information, please feel free to send us a message using the help beacon in the lower right-hand corner.