DocDroid
v1.2.0
OpenAPI 3.0.0

DocDroid REST API

The DocDroid REST API is available at https://www.docdroid.com/api and allows to

  • Upload, edit, delete and list documents.
  • Request anaytics data (Pro accounts only).
  • Subscribe to webhooks.

Authentication

You can use OAuth v2.0 to authenticate to the DocDroid REST API. You can create your personal access token to perform requests.

For every API request, a valid access token must be provided in an HTTP header: Authorization: Bearer {access_token}

If you plan to perform requests in behalf of user's DocDroid accounts, you need to create a client. After creating a client, your app should redirect users to https://www.docdroid.com/oauth/authorize in order to obtain access tokens.

Rate Limiting

There is general limit of 60 requests per minute. Additional, the number of uploads is limited:

  • Standard accounts: 10 uploads per 24h
  • Pro accounts: 1000 uploads per 24h

If the limit is exceeded, you will receive the HTTP error: 429 Too Many Requests.

Changelog

  • 1.0 - 1.08.2017: Initial Release of the DocDroid REST API
  • 1.1 - 21.11.2017: Add new settings for documents: allow_download, allow_search_engines_index, allow_embed, allow_embed_domains.
  • 1.2 - 15.02.2019: Add new setting for documents: allow_copy_text.
Server:https://www.docdroid.com/api
Client Libraries
Shell Curl

document

​

document

document Operations

List my documents

​
OAuth scopes
  • view-documents
Query Parameters
  • page
    Type: integer

    The current page to query

  • per_page
    Type: integer

    Number of items to show per page

  • sort
    Type: string

    Sort result by field

Responses
  • application/json
Request Example for get/document
curl https://www.docdroid.com/api/document \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "id": "hptvUCe",
      "filename": "Example.pdf",
      "name": "Example",
      "ext": "pdf",
      "status": "ok",
      "type": "document",
      "visibility": "public",
      "allow_download": true,
      "allow_search_engines_index": true,
      "allow_embed": "any",
      "allow_embed_domains": [
        "domain.com",
        "www.domain.net"
      ],
      "allow_copy_text": true,
      "password": "secret",
      "links": [
        {
          "rel": "shortlink",
          "href": "https://docdro.id/hptvUCe"
        }
      ]
    }
  ]
}

A list of your documents

Upload a new document

​
OAuth scopes
  • upload-documents
Body
required
application/json
Responses
  • application/json
  • 422

    Invalid request

Request Example for post/document
curl https://www.docdroid.com/api/document \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --form 'file=' \
  --form 'visibility=public' \
  --form 'type=document' \
  --form 'allow_embed=any' \
  --form 'allow_embed_domains='

{
  "data": {
    "id": "hptvUCe",
    "filename": "Example.pdf",
    "name": "Example",
    "ext": "pdf",
    "status": "ok",
    "type": "document",
    "visibility": "public",
    "allow_download": true,
    "allow_search_engines_index": true,
    "allow_embed": "any",
    "allow_embed_domains": [
      "domain.com",
      "www.domain.net"
    ],
    "allow_copy_text": true,
    "password": "secret",
    "links": [
      {
        "rel": "shortlink",
        "href": "https://docdro.id/hptvUCe"
      }
    ]
  }
}

The created document

View a document

​
OAuth scopes
  • view-documents
Path Parameters
  • id
    Type: string
    required

    The ID of the document

Responses
  • application/json
  • 403

    Unauthorized to view this document

Request Example for get/document/{id}
curl 'https://www.docdroid.com/api/document/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": {
    "id": "hptvUCe",
    "filename": "Example.pdf",
    "name": "Example",
    "ext": "pdf",
    "status": "ok",
    "type": "document",
    "visibility": "public",
    "allow_download": true,
    "allow_search_engines_index": true,
    "allow_embed": "any",
    "allow_embed_domains": [
      "domain.com",
      "www.domain.net"
    ],
    "allow_copy_text": true,
    "password": "secret",
    "links": [
      {
        "rel": "shortlink",
        "href": "https://docdro.id/hptvUCe"
      }
    ]
  }
}

The document

Update a document

​
OAuth scopes
  • edit-documents
Path Parameters
  • id
    Type: string
    required

    The ID of the document

Body
application/json
Responses
  • application/json
  • 403

    Unauthorized to edit this document

  • 422

    Invalid request

Request Example for put/document/{id}
curl 'https://www.docdroid.com/api/document/{id}' \
  --request PUT \
  --header 'Content-Type: multipart/form-data' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --form 'visibility=public' \
  --form 'type=document' \
  --form 'allow_embed=any' \
  --form 'allow_embed_domains='

{
  "data": {
    "id": "hptvUCe",
    "filename": "Example.pdf",
    "name": "Example",
    "ext": "pdf",
    "status": "ok",
    "type": "document",
    "visibility": "public",
    "allow_download": true,
    "allow_search_engines_index": true,
    "allow_embed": "any",
    "allow_embed_domains": [
      "domain.com",
      "www.domain.net"
    ],
    "allow_copy_text": true,
    "password": "secret",
    "links": [
      {
        "rel": "shortlink",
        "href": "https://docdro.id/hptvUCe"
      }
    ]
  }
}

The updated document

Delete a document

​
OAuth scopes
  • edit-documents
Path Parameters
  • id
    Type: string
    required

    The ID of the document

Responses
  • 204

    No content

  • 403

    Unauthorized to delete this document

Request Example for delete/document/{id}
curl 'https://www.docdroid.com/api/document/{id}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Body

No content

analytics

​

analytics

analytics Operations

Get the views per country

​
OAuth scopes
  • analytics
Query Parameters
  • document
    Type: string

    Limit query by document ID. Separate multiple documents by comma.

Responses
  • application/json
Request Example for get/analytics/countries
curl https://www.docdroid.com/api/analytics/countries \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "countryCode": "string",
      "country": "string",
      "views": 1
    }
  ]
}

The analytics report

Get the views per day

​
OAuth scopes
  • analytics
Query Parameters
  • document
    Type: string

    Limit query by document ID. Separate multiple documents by comma.

Responses
  • application/json
Request Example for get/analytics/days
curl https://www.docdroid.com/api/analytics/days \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "day": "string",
      "views": 1,
      "unique": 1
    }
  ]
}

The analytics report

Get the views and average view time per page

​
OAuth scopes
  • analytics
Query Parameters
  • document
    Type: string

    Limit query by document ID. Separate multiple documents by comma.

Responses
  • application/json
Request Example for get/analytics/pages
curl https://www.docdroid.com/api/analytics/pages \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "page": 1,
      "views": 1,
      "avgtime": 1
    }
  ]
}

The analytics report

Get the views per document

​
OAuth scopes
  • analytics
Query Parameters
  • document
    Type: string

    Limit query by document ID. Separate multiple documents by comma.

Responses
  • application/json
Request Example for get/analytics/documents
curl https://www.docdroid.com/api/analytics/documents \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "id": "string",
      "title": "string",
      "views": 1
    }
  ]
}

The analytics report

Get the number of downloads

​
OAuth scopes
  • analytics
Query Parameters
  • document
    Type: string

    Limit query by document ID. Separate multiple documents by comma.

Responses
  • application/json
Request Example for get/analytics/downloads
curl https://www.docdroid.com/api/analytics/downloads \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "type": "string",
      "downloads": 1,
      "delta": 1
    }
  ]
}

The analytics report

Get the number of views

​
OAuth scopes
  • analytics
Query Parameters
  • document
    Type: string

    Limit query by document ID. Separate multiple documents by comma.

Responses
  • application/json
Request Example for get/analytics/views
curl https://www.docdroid.com/api/analytics/views \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "views": 1,
      "delta": 1
    }
  ]
}

The analytics report

Get the number of views by referrer

​
OAuth scopes
  • analytics
Query Parameters
  • document
    Type: string

    Limit query by document ID. Separate multiple documents by comma.

Responses
  • application/json
Request Example for get/analytics/referrers
curl https://www.docdroid.com/api/analytics/referrers \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "referrer": "string",
      "views": 1
    }
  ]
}

The analytics report

Get the number of clicks by outbound link

​
OAuth scopes
  • analytics
Query Parameters
  • document
    Type: string

    Limit query by document ID. Separate multiple documents by comma.

Responses
  • application/json
Request Example for get/analytics/outbound
curl https://www.docdroid.com/api/analytics/outbound \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "id": "string",
      "title": "string",
      "link": "string",
      "clicks": 1
    }
  ]
}

The analytics report

webhooks

​

webhooks

webhooks Operations

List my webhooks

​
OAuth scopes
  • webhooks
Responses
  • application/json
Request Example for get/webhook
curl https://www.docdroid.com/api/webhook \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "id": 123,
      "event": "document.uploaded",
      "target_url": "https://requestb.in/test"
    }
  ]
}

A list of your webhooks

Create a new webhook

​
OAuth scopes
  • webhooks
Body
required
application/json
  • event
    Type: string enum
    required
    values
    • document.created
    • document.uploaded
    • document.updated
    • document.deleted
  • target_url
    Type: string
    required
Responses
  • application/json
  • 422

    Invalid request

Request Example for post/webhook
curl https://www.docdroid.com/api/webhook \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "event": "document.created",
  "target_url": ""
}'

{
  "data": {
    "id": 123,
    "event": "document.uploaded",
    "target_url": "https://requestb.in/test"
  }
}

The created webhook

View a webhook

​
OAuth scopes
  • webhooks
Path Parameters
  • id
    Type: integer
    required

    The ID of the webhook

Responses
  • application/json
Request Example for get/webhook/{id}
curl https://www.docdroid.com/api/webhook/1 \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": {
    "id": 123,
    "event": "document.uploaded",
    "target_url": "https://requestb.in/test"
  }
}

The webhook

Delete a webhook

​
OAuth scopes
  • webhooks
Path Parameters
  • id
    Type: integer
    required

    The ID of the webhook

Responses
  • 204

    No content

Request Example for delete/webhook/{id}
curl https://www.docdroid.com/api/webhook/1 \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Body

No content