openapi: 3.2.0
info:
title: Canoe API v1 Password Grant Tokens API
version: 1.0.0
description: "Canoe's API provides methods for retrieving extracted data from documents and their metadata as well as data from downloaded PDFs. This documentation includes detailed explanations of API endpoints and examples. You may not have access to all of the listed endpoints depending on the services you've purchased from Canoe as well as your user permissions.\n<p>By using Canoe’s API Documentation, you agree to the most recent version of <a href=\"https://canoeintelligence.com/api-terms-of-use/\" target=\"_blank\"><u>Canoe’s Developer Portal Terms of Use.</u></a></p>\n<p>In addition to the <code class=\"prettyprint\">curl</code>, <code class=\"prettyprint\">javascript</code>, <code class=\"prettyprint\">python</code>, <code class=\"prettyprint\">php</code> and <code class=\"prettyprint\">CSharp</code> examples next to each endpoint, we've also included a <a href=\"https://www.getpostman.com\" target=\"_blank\"><u>Postman</u></a> collection. The collection contains API calls for each available endpoint. Postman is a tool that helps generate and test API calls by providing a clean interface to build and save HTTP requests, and to check and test API responses. </p>\n\n<p>\n Note: Download Postman from their official website. Find out more about how to import Postman collections <a href=\"https://learning.getpostman.com/docs/postman/collections/data_formats/#importing-postman-data\" target=\"_blank\"><u>here</u></a>.\n</p>\n<p>\n Your information security team may require whitelisting Canoe’s IP addresses before you can call the API. Whitelist the IP addresses found in <a href=\"https://client.canoesoftware.com/knowledge-base#/api/canoe-api-overview\" target=\"_blank\"><u>this knowledge base page</u></a> to allow all API addresses of Canoe. <b>(Note: You must be logged into your Canoe account to access the knowledge base page)</b>\n</p>\n<p>\n Your information technology team may require you to open ports to call the API. The API uses port numbers 443 and 9443.\n</p>\n<p>\n Additionally, your information security team may request that Canoe limit the IP address(es) from which you can make API calls as an extra layer of data protection. If so, please reach out to our support team.\n</p>\n\n<br>\n<strong><u>Request:</u></strong>\n\nThe base URL for all Canoe API requests is <code class=\"prettyprint\">https://api.canoesoftware.com</code>\n\nThe API is built on RESTful principles with resource-oriented URL endpoints. HTTP status codes are used to indicate any API errors and all responses are returned in JSON format. All requests must be made over an HTTPS connection to ensure a secure transmission of data. Following a RESTful structure, requests should hit API endpoints using the appropriate HTTP method, which will depend on the desired action:\n\n<table><thead>\n <tr>\n <th>Method</th>\n <th>Description</th>\n </tr>\n </thead><tbody>\n <tr>\n <td>GET</td>\n <td>Use the <strong>GET</strong> method to retrieve information about your users, their organizations, and available associated data. This will always be a read-only request, so queried objects will never be modified by a GET request. When using filter parameters that include special characters, you should always encode those values to fit URI specifications.</td>\n </tr>\n <tr>\n <td>POST</td>\n <td>Use a <strong>POST</strong> method to create a new object, such as a new user or organization. Request parameters should be given in JSON format. The response body will typically return the newly created resource.</td>\n </tr>\n <tr>\n <td>PUT</td>\n <td>Use a <strong>PUT</strong> method to update an object, such as updating user credentials. As with a POST request, parameters should be given in JSON format. If successful, the response body will typically return the modified object.</td>\n </tr>\n <tr>\n <td>DELETE</td>\n <td>Use a <strong>DELETE</strong> method to delete an object, such as deleting one of your funds. Successful DELETE requests will typically return an empty response body.</td>\n </tr>\n </tbody></table>\n\n\n<strong><u>Response:</u></strong>\n\n<p>All non-empty response bodies, including errors, will be formatted as a JSON object. If you are fetching multiple entries, such as <code class=\"prettyprint\">/v1/funds</code> example, the data will be returned as a list. If you are fetching a single entry, such as <code class=\"prettyprint\">GET /v1/funds/1</code>, the data will be returned as a single object.</p>\n<p>Canoe's APIs use standard HTTP status codes to indicate the status of a request.</p>\n<p>Below is a brief overview of the most common status codes:</p>\n<table><thead>\n <tr>\n <th>Code</th>\n <th>Text</th>\n <th>Definition</th>\n </tr>\n </thead><tbody>\n <tr>\n <td>200</td>\n <td>OK</td>\n <td>Success!</td>\n </tr>\n <tr>\n <td>400</td>\n <td>Bad Request</td>\n <td>The request was invalid or cannot be otherwise served. This could be due to an invalid or malformed parameter, etc.</td>\n </tr>\n <tr>\n <td>401</td>\n <td>Unauthorized</td>\n <td>The API authentication credentials or access token are missing or incorrect.</td>\n </tr>\n <tr>\n <td>403</td>\n <td>Forbidden</td>\n <td>The credentials or access token are authenticated, but you do not have access to the requested resource.</td>\n </tr>\n <tr>\n <td>404</td>\n <td>Not Found</td>\n <td>The requested resource is invalid or the resource requested, such as a Fund, does not exist. The 404 status code might indicates that the REST API can't map the client's URI to a resource but may be available in the future.</td>\n </tr>\n <tr>\n <td>405</td>\n <td>Method Not Allowed</td>\n <td>The request tried to use an HTTP method that the resource does not allow. For instance, a read-only resource could support only GET, but not PUT or DELETE or POST.</td>\n </tr>\n <tr>\n <td>500</td>\n <td>Internal Server Error</td>\n <td>There are internal or API-related errors on Canoe's side. Additional requests will not resolve the issue.</td>\n </tr>\n <tr>\n <td>503</td>\n <td>Service Unavailable</td>\n <td>The Canoe servers are up, but overloaded with requests. Try again later.</td>\n </tr>\n </tbody></table>\n"
contact:
name: Canoe Support
url: https://canoeintelligence.com
termsOfService: https://canoeintelligence.com/api-terms-of-use/
servers:
- url: https://api.canoesoftware.com
description: Production API
security:
- bearerAuth: []
tags:
- name: Password Grant Tokens
description: ''
paths:
/v1/tokens:
post:
tags:
- Password Grant Tokens
summary: Get an access token
description: Access tokens provide access to all other endpoints within the API. This endpoint allows you to request access tokens securely without going through the OAuth2 authorization code redirect flow.
operationId: Tokens
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: Your username. This will be the email address associated with your account.
example: abc@xyz.com
password:
type: string
description: Your password.
example: ab**9Pe+_.^3a!@~yql
organization_id:
type: string
description: The organization you would like to be authenticated under (this is required if your user has access to multiple organizations).
example: account_1
required:
- username
- password
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Token'
x-codeSamples:
- lang: bash
label: Bash
source: "curl -X POST \\\n \"https://api.canoesoftware.com/v1/tokens\" \\\n -H \"Authorization: Bearer {token}\" \\\n -H \"Accept: application/json\" \\\n -H \"X-Requested-With: XMLHttpRequest\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"username\":\"abc@xyz.com\",\"password\":\"ab**9Pe+_.^3a!@~yql\"}'"
- lang: javascript
label: JavaScript
source: "const url = new URL(\n \"https://api.canoesoftware.com/v1/tokens\"\n );\n\n let headers = {\n \"Authorization\": \"Bearer {token}\",\n \"Accept\": \"application/json\",\n \"X-Requested-With\": \"XMLHttpRequest\",\n \"Content-Type\": \"application/json\",\n };\n\n let body = {\n \"username\": \"abc@xyz.com\",\n \"password\": \"ab**9Pe+_.^3a!@~yql\"\n }\n\n fetch(url, {\n method: \"POST\",\n headers: headers,\n body: body\n })\n .then(response => response.json())\n .then(json => console.log(json));"
- lang: php
label: PHP
source: "$client = new \\GuzzleHttp\\Client();\n $response = $client->post(\n 'https://api.canoesoftware.com/v1/tokens',\n [\n 'headers' => [\n 'Authorization' => 'Bearer {token}',\n 'Accept' => 'application/json',\n 'X-Requested-With' => 'XMLHttpRequest',\n 'Content-Type' => 'application/json',\n ],\n 'json' => [\n 'username' => 'abc@xyz.com',\n 'password' => 'ab**9Pe+_.^3a!@~yql',\n ],\n ]\n );\n $body = $response->getBody();\n print_r(json_decode((string) $body));"
- lang: python
label: Python
source: "import requests\n import json\n\n url = 'https://api.canoesoftware.com/v1/tokens'\n payload = {\n \"username\": \"abc@xyz.com\",\n \"password\": \"ab**9Pe+_.^3a!@~yql\"\n }\n headers = {\n 'Authorization': 'Bearer {token}',\n 'Accept': 'application/json',\n 'X-Requested-With': 'XMLHttpRequest',\n 'Content-Type': 'application/json'\n }\n response = requests.request('POST', url, headers=headers, json=payload)\n response.json()"
- lang: csharp
label: CSharp
source: "using RestSharp;\n\n var client = new RestClient(\"https://api.canoesoftware.com/\");\n var request = new RestRequest(\"v1/tokens\", Method.Post);\n request.AddHeader(\"Accept\", \"application/json\");\n request.AddHeader(\"X-Requested-With\", \"XMLHttpRequest\");\n request.AddHeader(\"Content-Type\", \"application/json\");\n var body = new\n {\n username = \"abc@xyz.com\",\n password = \"ab**9Pe+_.^3a!@~yql\"\n };\n request.AddJsonBody(body);\n var response = client.Execute(request);\n Console.WriteLine(response.Content);"
security: []
components:
schemas:
Token:
type: object
properties:
token_type:
type: string
description: A parameter in the Access Token generation call within the Authorization server. This represents how an access_token will be generated and presented for resource access calls.
example: Bearer
expires_in:
type: integer
description: The lifetime in seconds of the access token. For example, the value 3600 denotes that the access token will expire in one hour from the time the response was generated.
example: 3600
access_token:
type: string
description: An access_token is a unique string of letters and numbers that you pass with an API call. The access token represents the authorization of a specific application to access specific parts of a user's data. Access tokens must be kept confidential both in transit and in storage.
example: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjM5YjA4ZmZkZjQ5ZmRiNDYxMzk4MTY0ODNkMGVlNmNjMjA2ZmYxMDU1ODVhMDUwM2ViZmY3Mzg4OTMzN2I4NTI5Mzg1MWY5ZTBjN2YzYzNmIn0.eyJhdWQiOiJhZjFhMjVjNC1hNDE3LTEx
ZTktOTZmYy0wNmY3NWI2ZjJiNGEiLCJqdGkiOiIz
OWIwOGZmZGY0OWZkYjQ2MTM5ODE2NDgzZDBlZTZjYzIwNmZmMTA1NTg1YTA1MDNlYmZmNzM4ODkzMzdiODUyOTM4NTFmOWUwYzdmM2MzZiIsImlhdCI6MTU2Mjg3NjI1MiwibmJmIjoxNTYyODc2MjUyLCJleHAiOjE1NjQx
NzIyNTEsInN1YiI6IjE2MzhlZDRhLTY4MTItYTNh
Yy0wMDA1LTUzYmI5MjJjNGFiYiIsInNjb3BlcyI6W
119.t7wflHG7Og9Vf1rqPWo2QzCyyAo3AUc9duZyoM
EQ8dix5Omt5OWqHX6TWYddxbC34fvRi1Gby4CqK9Kz-s-0GMr2YnWxBPCzAIGlKMRVKbs615bQTpChG0a5BWzcUMOww1zhL9Gz8aSg2yI47kAHFnVPZFGH4zA2yqcRvmg7QvoYzQcm4hJR6NatMJgKOChagUDthdj-ezWwWq_pyCXZFU2XwLm1vBZTIkgG40uCbqgsEUffDXFibQypBG9BrUkw03o9wh72UoL-QeMHn5K5Q7zJx08pzOUXWm_W4pfO7FIwzaHoOEtFmorSihnw7gzDddwASwMzhYgqF839J7CLa_mq6YV53oMP2eCOKX0jN-dd
Eg4Gt6yYkVbh54yOsbztc4P1waUJ4JnJsBV2GdWd
xnB0bhx6QFhj4HrnkQzx1GScFjRzKPHJGGmN9e-6wCEb7TXncbtnuu-8YxCbG5IUfc25BlBtMeqURE1A6Pa7YciBJoPLlEDUAJ8HwfSHspxDkuPhz1ospacDJgl
xHn18Mrkt8lukwIL7dfhM9Wm2b6ZBJrKngFdkFV9ALFImjBwqk2SZVfhLMYvhTG36qGqI7e7uw_SyU2lPiN2MQcVpdaSd0NkCLqGAkRRwuDCaHBfZ35TJguJXHdJuRMDoghUAhYgAwqp7OU1FtgX1gmt5tok'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Enter your Bearer token in the format: Bearer {token}'
oauth2:
type: oauth2
description: OAuth 2.0 authentication
flows:
authorizationCode:
authorizationUrl: https://api.canoesoftware.com/oauth/authorize
tokenUrl: https://api.canoesoftware.com/oauth/token
scopes: {}
clientCredentials:
tokenUrl: https://api.canoesoftware.com/v1/tokens
scopes: {}
externalDocs:
description: Click to download docs in JSON format
url: /api/docs.json
x-tagGroups:
- name: Getting Started
tags:
- Introduction
- Authentication
- Password Grant Tokens
- name: Core Resources
tags:
- Documents
- Funds
- Terms
- Organizations
- Allocations
- name: User Management
tags:
- User