Skip to main content
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

In this example, we will use Python’s requests library to interact with FlashDocs REST API.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}",
}

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

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
ParameterTypeDefault / DescriptionRequired
google_document_linkqueryThe link to the Google Slides documentYes
document_typequeryPossible values: “template”, “library”No
namequeryName of presentationNo
descriptionqueryDescription of presentationNo
reset_text_boxesqueryIf “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"
}
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
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.
EndpointGET /v1/documents/{document_id}/fullParameters
ParameterTypeQuery / PathDefault ValueDescriptionRequired
document_idstringpath-The ID of the document you want to retrieve.Yes
include_slidesbooleanqueryfalseWhether to include slides in the response.No
include_questionsbooleanqueryfalseWhether to include questions in the response.No
include_knowledge_basebooleanqueryfalseWhether to include knowledge base items in the response.No
include_embeddingsbooleanqueryfalseWhether 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)
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
EndpointDELETE /v1/documents/{document_id}
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.
NameTypeRequiredDescriptionAllowed Values
document_typeenum<string>
null
NoDocument type to filter by. If not provided, all documents will be returned.template, library
formatenum<string>
null
NoDocument 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:
FieldTypeRequiredDescriptionDefault / Allowed Values
descriptionstringYesDetailed description of the document
namestringYesName of the document
organization_idstringYesID of the organization this document belongs to
typeenum<string>YesType of the documenttemplate, library
created_atstringNoCreation timestamp
created_bystringNoEmail of user (non FlashDocs) who created the document
formatenum<string>NoFormat of the documentgoogle, microsoft (default: google)
google_document_idstring
null
NoID of the corresponding Google Slides document
idstringYesUnique identifier
knowledge_base_item_idsstring[]NoItem IDs for each knowledge base item associated with the document
statusenum<string>NoCurrent status of the documentdeployed, in_progress (default: in_progress)
updated_atstringNoLast 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