Welcome to RedShred API Client’s documentation!

Basic Usage

Authenticating the client

There are a few different options for authentication; by explicitly specifying the server information, using a RedShred configuration file, or using environmental variables. For the time being we will only discus the first option, but you can rever to the API documentation for more information on the others.

Here is how you would authenticate with explicit credentials:

Authentication with RedShred using explicit credentials

from redshred import RedShredClient
client = RedShredClient(token="ae6daceef240103b2b9e9b562ff6784690cdd0fb", host="https://api.redshred.com"
print(client.user.json(indent=2))

{
  "active": true,
  "email": "johndoe@theinternet.com",
  "first_name": "John",
  "joined": "2022-11-15T15:40:56.928582+00:00",
  "last_login": "2023-01-24T15:59:24.019915+00:00",
  "last_name": "Doe",
  "username": "johndoe@theinternet.com"
}

Congratulations, you are now authenticated!

Creating Collections and Documents

In order to process and upload documents, we need a collection to store them in.

creating a collection called “my-collection”

from redshred import Collection

# Create the collection object locally
collection = Collection(slug="my-collection")

# associate it with our client and create it remotely
collection.create(client)

print(collection.yaml())

output

config: {}
created_at: '2023-01-24T19:44:27.874546'
created_by: johndoe@theinternet.com
description: null
documents_link: https://api.dev.redshred.com/v2/collections/my-collection/documents
id: ETiN7a7EAsNYb2CwX4zkvY
marked_for_delete: null
metadata: null
name: null
owner: johndoe@theinternet.com
perspectives_link: https://api.dev.redshred.com/v2/collections/my-collection/perspectives
segments_link: https://api.dev.redshred.com/v2/collections/my-collection/segments
self_link: https://api.dev.redshred.com/v2/collections/my-collection
slug: my-collection
updated_at: '2023-01-24T19:44:27.874563'
updated_by: johndoe@theinternet.com
user_data: {}

Once we have created a collection we will want to upload a document:

uploading a document from a local file “my-document.pdf”

# First we can retrieve the collection we created above using similar syntax as creating it
collection = client.collection("my-collection")
document = collection.upload_file("/home/johndoe/Documents/my-document.pdf")

print(document.json(indent=2)))

output

{
  "self_link": "https://api.dev.redshred.com/v2/collections/my-collection/documents/aE9J62ZR7RAhVYaCeSwftJ",
  "id": "aE9J62ZR7RAhVYaCeSwftJ",
  "collection_link": "https://api.dev.redshred.com/v2/collections/my-collection",
  "collection_slug": "my-collection",
  "config": null,
  "content_hash": "22132ba64ec6bf79eabbba1b57ce9c8d8663bbc0e1252f17032f79b693d2edfa",
  "created_at": "2023-01-24T19:50:26.839768+00:00",
  "created_by": "johndoe@theinternet.com",
  "csv_metadata": null,
  "description": null,
  "document_segment_link": null,
  "errors": null,
  "file_link": "https://api.dev.redshred.com/v2/files/my-collection/s22132ba64ec6bf79eabbba1b57ce9c8d8663bbc0e1252f17032f79b693d2edfa.pdf?name=my-document.pdf",
  "file_size": 21367,
  "index": 1,
  "metadata": null,
  "n_pages": null,
  "name": "my-document.pdf",
  "original_name": "my-document.pdf",
  "pages_link": "https://api.dev.redshred.com/v2/collections/my-collection/documents/aE9J62ZR7RAhVYaCeSwftJ/pages",
  "pdf_link": "https://api.dev.redshred.com/v2/files/my-collection/s22132ba64ec6bf79eabbba1b57ce9c8d8663bbc0e1252f17032f79b693d2edfa.pdf",
  "perspectives_link": "https://api.dev.redshred.com/v2/collections/my-collection/documents/aE9J62ZR7RAhVYaCeSwftJ/perspectives",
  "read_state": "queued",
  "read_state_updated_at": "2023-01-24T19:50:26.961375+00:00",
  "region": {
    "coordinates": [
      [
        [0.0, 0.0],
        [1.0, 0.0],
        [1.0, 1.0],
        [0.0, 1.0],
        [0.0, 0.0]
      ]
    ],
    "type": "Polygon"
  },
  "segments_link": "https://api.dev.redshred.com/v2/collections/my-collection/documents/aE9J62ZR7RAhVYaCeSwftJ/segments",
  "slug": "my-documentpdf",
  "source": "file",
  "summary": null,
  "text": null,
  "updated_at": "2023-01-24T19:50:26.894566+00:00",
  "updated_by": "johndoe@theinternet.com",
  "user_data": null,
  "warnings": null,
}

We notice above that most of the information we would expect to see, like text or n_pages is empty. This is because the document is still reading! We can wait for the document to read and see what’s different from above like so:

waiting until the document is read

document.wait_until_read() # the interpreter will pause here until the document has finished reading remotely
print(document.yaml(include={"text", "n_pages"}))

the output with only the specified fields displayed

n_pages: 2
text: The rain in Spain stays mainly in the plain...

Accessing and Interacting with API Objects

Printing all paragraphs in a document a few different ways

for collection in client.collections():
   print(f"{collection.slug!r} created at {collection.created_at} by {collection.created_by}")
   if collection.slug == "my-collection":
      print("my-collection found!")
      break

# First we find our document. Since we know we only have one with the title "my-document.pdf", we can just
# just get the first search result from querying the server via its attributes
document = collection.documents(name="my-document.pdf").first()

# we can then do a similar operation to find our text perspective, called "typography" and all of its paragraph
# segments
typography_perspective = document.perspectives(name="typography").first()
for segment in typography_perspective.segments(segment_type="paragraph"):
   print(f"paragraph id: {segment.id}")
   print(segment.text)

output

'my-other-collection' created at 2023-01-24 19:44:27.874546+00:00 by johndoe@theinternet.com
'my-collection' created at 2023-01-11 17:37:03.342783+00:00 by johndoe@theinternet.com
my-collection found!

paragraph id: WmXRmpJVseMgdGL5TbM8b6
The rain in Spain stays mainly in the plain

RSQL Call Query Creation

The Redshred API supports RSQL (Redshred Query Language) for advanced querying. The client library provides a safe way to construct these queries using string templates and automatic escaping of special characters.

Basic Query

For simple queries, you can pass a string directly:

 rs = RedShredClient()
 collections = rs.collections(q='text="rose" and segment_type="paragraph"')

Welcome to RedShred API Client’s documentation!

Basic Usage

Authenticating the client

Creating Collections and Documents

Accessing and Interacting with API Objects

RSQL Call Query Creation

Basic Query

Template with Values

Special Character Handling

Common Use Cases

API Documentation

Indices and tables