Configure FlashDocs Documents Via API

See a video walk-through here

You can create, view, and edit your organization’s FlashDocs templates & libraries at: https://dash.flashdocs.ai This tutorial will show you how to do the following:

Authenticate

Upload a Google Slides presentation and convert it into a FlashDocs Library

View your uploaded document

Crash Course on How FlashDocs Works

Before continuing, make sure you know:

The difference between a Template and a Library in FlashDocs
- A FlashDocs template is a series of slides with placeholders. When a template deck is generated, it uses the all of the slides in the specified order and customizes the placeholder values to the given context.
- A FlashDocs library is a large set of slides. When a custom deck is created, specific slides from the library are selected based on the context of the deck. The placeholders in these slides are customized to the given context.
A general idea about placeholders in a FlashDocs document and how FlashDocs uses them to create custom presentations.

Crash Course

Learn the basics of how FlashDocs works in 60 seconds.

Set-Up

Auth Token & Base URL

In this example, we will use Python’s requests library to interact with FlashDocs REST API.

Base URL: https://api.flashdocs.ai

Replace YOUR_AUTH_TOKEN with your actual token. Keep your token secret.

import requests
import pprint
import time
# ================================
#        Configuration
# ================================
API_BASE_URL = "https://api.flashdocs.ai"
AUTH_TOKEN = "YOUR_AUTH_TOKEN"  # <-- Replace with your actual token

# Standard headers
headers = {
    "Authorization": f"Bearer {AUTH_TOKEN}",
}

(Optional) User

EndpointGET /v1/auth/userWhen called with a valid Authorization: Bearer <token> header, this endpoint will return the User object representing the currently authenticated user.Example Response

{
  "email": "bob@acme.com",
  "id": "abcdef-ghijk-lmnop-123",
  "organization_id": "acme.com"
}

 def get_current_user():
    """
    Makes a GET request to /v1/auth/user to retrieve 
    the currently signed-in user's information.
    """
    endpoint = f"{API_BASE_URL}/v1/auth/user"
    response = requests.get(endpoint, headers=headers)
    if response.status_code == 200:
        user_info = response.json()
        print("User info retrieved successfully!")
        return user_info
    else:
        print(f"Failed to retrieve user info. Status code: {response.status_code}")
        print("Response:", response.text)
        return None

# Example usage:
user_data = get_current_user()
pprint.pprint(user_data)

Upload Documents

FlashDocs supports Google Slides and PowerPoint - in this example, we create a FlashDocs Library from a Google Slides document. After uploading a presentation, you can create endless decks from it using the launch endpoint.

Intuition

FlashDocs generates decks by choosing relevant slides from the master deck and then replacing all of the text, images, and charts in the slide depending on the user’s prompt + context.

Deck Creation

FlashDocs generates decks by choosing relevant slides from the master deck and then replacing all of the text, images, and charts in the slide depending on the user’s prompt + context.

Standardization

FlashDocs standardizes and processes the slides to make them usable for programmatic creation.

- Changes all text to placeholders - If reset_test_boxes=true
- Identifies image placeholders (logos)
- and more…

For best performance, include lots of slides in the library so the system can find a relevant layout for each slide generation.

Upload Endpoints

Create Google Slides Library

EndpointPOST /v1/documents/google

View the API Reference here

This endpoint is used to upload a Google Slides link and create a template or library in your organization. In this example, we’ll convert your Google Slides presentation into a library. Depending on the number of slides, it may take a few minutes (ex: 50 slides may take 3 minutes). If the speed of upload is a concern, let us know and we can easily speed it up an order of magnitude.If you have a deck with text placeholders already enclosed in brackets ([, ]), then reset_text_boxes=false will automatically identify and capture them. Otherwise, given a deck with text already populated, with reset_text_boxes=true the system will reset all text to placeholders.Request Parameters

Parameter	Type	Default / Description	Required
google_document_link	query	The link to the Google Slides document	Yes
document_type	query	Possible values: “template”, “library”	No
name	query	Name of presentation	No
description	query	Description of presentation	No
reset_text_boxes	query	If “true”, then converts all text boxes into placeholders. Else, only identifies bracketed text as placeholders.	No

Example Response

{
    "message": "Document created successfully",
    "success": true,
    "document_id": "abc-defghi-1234-5"
}

{
    "message": "Document upload failure <error details>",
    "success": false
}

Below is a code snippet that calls the REST API.

def upload_google_presentation_as_library(google_document_link, name="Library", description="Some description", reset_text_boxes=False):
    """
    Upload a Google Slides link to create a Library document.
    """
    endpoint = f"{API_BASE_URL}/v1/documents/google"
    
    params = {
        "google_document_link": google_document_link,
        "document_type": "library",  # "template" if you just want a template
        "name": name,
        "reset_text_boxes": reset_text_boxes,
        "description": description
    }
    
    response = requests.post(endpoint, headers=headers, params=params)
    if response.status_code == 200:
        print("Successfully uploaded presentation as a library!")
        return response.json()
    else:
        print("Failed to upload. Status code:", response.status_code)
        print("Response:", response.text)
        return None

Create PowerPoint Library

EndpointPOST /v1/documents/ppt

View the API Reference here

Example Usage (Google)

Feel free to use your own Google Document Link. For demonstration purposes, we created a sample library with a handful of slides: Google Slide Sample Library [Original]. The document is public, so feel free to check it out. Here is a duplicated result of the deck after the text boxes are reset: View Only Google Slide Sample Library [After Upload]

Note that in the output deck (result after calling endpoint), all of the text is transformed into placeholders (with square brackets around categories of text). This happens because the example includes reset_text_boxes=true, which identifies all text elements and transforms them into FlashDocs text placeholders.

Using the upload_google_presentation_as_library function defined in the “Create Google Slides Library” section:

# Example usage:
google_document_link = None # duplicate the presentation here (https://docs.google.com/presentation/d/1taWinZy10_cw04JvhON__gGsyowbhQ_8Td8A9EVngvs/edit#slide=id.g2a508a5a28e_0_562) and then paste the link

# This will take a few minutes. If speed is a priority, let us know and we can speed it up by an order of magnitude.
library_response = upload_google_presentation_as_library(
    google_document_link=google_document_link,
    name="Master Library",
    description="For client-facing purposes.",
    reset_text_boxes=True
)
pprint.pprint(library_response)

Error Handling For Google Slides presentations, our service worker must be able to access and edit the document. You might be asked to manually share the document with flashy@flashdocs.ai, flashy1@flashdocs.ai, flashy2@flashdocs.ai, and flashy2@flashdocs.ai Contact adam@flashdocs.ai if you have any unexpected difficulties.

View and Edit Your Uploaded Document

After successfully uploading your document, you may want to verify its full details, including the placeholders created within each slide. The FlashDocs API offers a route to fetch the complete document object, where you can specify which parts (slides, questions, knowledge base items, or embeddings) you want included in the response.

Read Full Document

EndpointGET /v1/documents/{document_id}/fullParameters

Parameter	Type	Query / Path	Default Value	Description	Required
document_id	string	path	-	The ID of the document you want to retrieve.	Yes
include_slides	boolean	query	`false`	Whether to include slides in the response.	No
include_questions	boolean	query	`false`	Whether to include questions in the response.	No
include_knowledge_base	boolean	query	`false`	Whether to include knowledge base items in the response.	No
include_embeddings	boolean	query	`false`	Whether to include embeddings in the response.	No

Example Request

GET /v1/documents/{document_id}/full?include_slides=true&include_questions=false&include_knowledge_base=false&include_embeddings=false

Example Response

{
  "id": "string",
  "created_at": "string",
  "updated_at": "string",
  "organization_id": "string",
  "type": "template",
  "created_by": "",
  "name": "string",
  "description": "string",
  "status": "in_progress",
  "google_document_id": "string",
  "knowledge_base_item_ids": [],
  "format": "google",
  "slides": [
    {
      "slide_id": "some_slide_id",
      "placeholders": [
         // your placeholder elements
      ],
      ...
    },
    // ...
  ],
  "questions": [],
  "knowledge_base_items": []
}

Below is a Python snippet that demonstrates how to retrieve the full document data:

def fetch_document_full_data(document_id, slides=True, questions=False, knowledge_base=False, embeddings=False):
    """
    Fetches the full document data (including slides) by specifying query parameters.
    """
    endpoint = f"{API_BASE_URL}/v1/documents/{document_id}/full"
    params = {
        "include_slides": str(slides).lower(),            # "true" or "false"
        "include_questions": str(questions).lower(),      
        "include_knowledge_base": str(knowledge_base).lower(),
        "include_embeddings": str(embeddings).lower()
    }
    
    response = requests.get(endpoint, headers=headers, params=params)
    if response.status_code == 200:
        full_data = response.json()
        print("Full document data retrieved successfully!")
        return full_data
    else:
        print(f"Failed to fetch full document data. Status code: {response.status_code}")
        print("Response:", response.text)
        return None

# Example usage:
# Suppose the response from upload_google_presentation_as_library
# is in a variable called library_response. Then:
document_id = library_response["document_id"]

document_full_data = fetch_document_full_data(document_id)
pprint.pprint(document_full_data)

Update Document / Slide

To update the metadata of a document (description, name, type (template/library)), use the following endpoint:EndpointPUT /v1/documents/{document_id}To update the attributes of a specific slide in the document (description, image_placeholders, text_placeholders, etc.), use the following endpoint:EndpointPUT /v1/slides/{slide_id}The slide_idcan be retrieved from a call to GET /v1/documents/{document_id}/full with include_slides=true

Delete Document

EndpointDELETE /v1/documents/{document_id}

View All Documents

Retrieve a list of documents from the system, with optional filtering by document type and format.

Endpoint

GET /v1/documents/base

Description

The List Documents endpoint allows you to fetch a collection of documents stored in the system. You can optionally filter the results by document_type and format. If no filters are applied, all documents will be returned.

Query Parameters

You can filter the documents by document_type and format. Both parameters are optional.

Name	Type	Required	Description	Allowed Values
document_type	`enum<string>` `null`	No	Document type to filter by. If not provided, all documents will be returned.	`template`, `library`
format	`enum<string>` `null`	No	Document format to filter by. If not provided, all documents will be returned.	`google`, `microsoft`

Response

A successful request returns a JSON array of document objects.

HTTP Status Code

200 OK

Response Body

Each document object contains the following fields:

Field	Type	Required	Description	Default / Allowed Values
description	`string`	Yes	Detailed description of the document
name	`string`	Yes	Name of the document
organization_id	`string`	Yes	ID of the organization this document belongs to
type	`enum<string>`	Yes	Type of the document	`template`, `library`
created_at	`string`	No	Creation timestamp
created_by	`string`	No	Email of user (non FlashDocs) who created the document
format	`enum<string>`	No	Format of the document	`google`, `microsoft` (default: `google`)
google_document_id	`string` `null`	No	ID of the corresponding Google Slides document
id	`string`	Yes	Unique identifier
knowledge_base_item_ids	`string[]`	No	Item IDs for each knowledge base item associated with the document
status	`enum<string>`	No	Current status of the document	`deployed`, `in_progress` (default: `in_progress`)
updated_at	`string`	No	Last update timestamp

Example Response

[
{
 "description": "Quarterly financial report",
 "name": "Q1 Financials",
 "organization_id": "org_12345",
 "type": "template",
 "created_at": "2024-01-15T08:30:00Z",
 "created_by": "user@example.com",
 "format": "google",
 "google_document_id": "google_doc_67890",
 "id": "doc_abcde",
 "knowledge_base_item_ids": ["kb_item_1", "kb_item_2"],
 "status": "deployed",
 "updated_at": "2024-02-20T10:45:00Z"
},
{
 "description": "Library of marketing slides",
 "name": "Marketing slides",
 "organization_id": "org_12345",
 "type": "library",
 "created_at": "2023-11-05T12:00:00Z",
 "created_by": "marketing@example.com",
 "format": "google",
 "google_document_id": null,
 "id": "doc_fghij",
 "knowledge_base_item_ids": [],
 "status": "in_progress",
 "updated_at": "2024-01-10T09:15:00Z"
}
]

Example Python Request

import requests

# Define the API endpoint
url = "https://api.example.com/v1/documents/base"

# Set up the headers with the Bearer token
headers = {
    "Authorization": f"Bearer {AUTH_TOKEN}",
    "Accept": "application/json"
}

# Define query parameters (optional)
params = {
    "document_type": "template",  # Optional: "template" or "library"
    "format": "google"            # Optional: "google" or "microsoft"
}

# Make the GET request
response = requests.get(url, headers=headers, params=params)

# Check if the request was successful
if response.status_code == 200:
    documents = response.json()
    for doc in documents:
        print(f"Document ID: {doc['id']}, Name: {doc['name']}")
else:
    print(f"Failed to retrieve documents. Status code: {response.status_code}")
    print(f"Error message: {response.text}")

User Interface For FlashDocs Document Updates

You can create, view, and edit your organization’s FlashDocs templates & libraries at: https://dash.flashdocs.ai

​Crash Course on How FlashDocs Works

Crash Course

​Set-Up

​

​

​Upload Documents

​Intuition

Deck Creation

Standardization

​Upload Endpoints

​Example Usage (Google)

​View and Edit Your Uploaded Document

​Example Request

​Example Response

​Endpoint

​Description

​Query Parameters

​Response

​HTTP Status Code

​Response Body

​Example Response

​Example Python Request

​User Interface For FlashDocs Document Updates

Crash Course on How FlashDocs Works

Set-Up

Upload Documents

Intuition

Upload Endpoints

Example Usage (Google)

View and Edit Your Uploaded Document

Example Request

Example Response

Endpoint

Description

Query Parameters

Response

HTTP Status Code

Response Body

Example Response

Example Python Request

User Interface For FlashDocs Document Updates