TheirStory API Guide

{
  "email": "user@example.com",
  "password": "yourpassword"
}

Response:

The response includes a JWT token and detailed information about the authenticated user.

Response Fields:

• token: JWT authentication token
• full_name: User's full name
• user_id: Unique identifier for the user
• role: User's role in the system (e.g., "admin")
• email: User's email address
• user_details: Detailed information about the user's profile
• organization_info: Information about the user's organization
• api_version: Version of the API
• create_gallery: Boolean permission for gallery creation

Example Response:

{
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaHR0cHM6Ly90aGVpcnN0b3J5LmlvL3Zpc2l0b3ItaWQiOiIwYWIxMmNkMy00NTY3LTg5MDEtMjM0NS02N2FiOGNkZTkwZjEiLCJpYXQiOjE2MjM0NTY3ODl9.AbCdEfGhIjKlMnOpQrStUvWxYz",
    "full_name": "John Doe",
    "user_id": "1234567890abcdef",
    "role": "admin",
    "email": "user@example.com",
    "user_details": {
        "id": 12345,
        "email": "user@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "photo_file_name": null,
        "photo_content_type": null,
        "organizations": [
            {
                "id": 67,
                "name": "Example Organization",
                "subdomain": "example",
                "custom_domain": "",
                "description": "
Example Organization is a platform that helps collect and preserve stories through interviews.
",
                "addresses": [
                    {
                        "address_line_1": "123 Main Street",
                        "address_line_2": "",
                        "city": "Anytown",
                        "state": "NY",
                        "zipcode": "12345",
                        "country": "US"
                    }
                ]
            }
        ]
    },
    "organization_info": {
        "permanent_org": {
            "export_allowed": true,
            "archive_nbr": "01ab-2345"
        },
        "settings": {
            "transcription_service": "cloudconvert",
            "filler_words": false,
            "vocabulary": [],
            "auto_chaptering": true,
            "summary_prompt": "Create a concise summary of this interview focusing on key topics discussed.",
            "chaptering_prompt": "Create an index for this interview with timecodes, titles, summaries, and keywords."
        },
        "branding": false,
        "_id": "abcdef1234567890",
        "activity": true,
        "org_manager_view_all": true,
        "export_allowed": true,
        "require_session_passwords": false,
        "local_recordings_allowed": true,
        "groups": [
            "group123",
            "group456",
            "group789"
        ],
        "organization_name": "Example Admin",
        "organizational_code": "example_admin_123456",
        "created_at": "2023-01-15T12:30:45.678Z",
        "__v": 5,
        "allow_dial_in": true,
        "local_recordings_polyfill": false,
        "credits": 1000000,
        "maxProjectsAllowed": 200,
        "projects": 150,
        "recording_hours": 320,
        "backgroundUrl": "uploads/projectbackgrounds/example-background-image.jpg"
    },
    "api_version": "1.2.3",
    "create_gallery": true
}

            fetch('https://node.theirstory.io/signin', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'Accept': 'application/json, text/plain, */*'
                },
                body: JSON.stringify({
                    email: email,
                    password: password
                })
            })
            .then(response => {
                if (response.ok) {
                    return response.json();
                }
                throw new Error('Login failed');
            })
            .then(data => {
                showMessage('Login successful! Redirecting...', 'success');
                // Store the token in localStorage for use in the organizations page
                localStorage.setItem('authToken', data.token);
                // Redirect to the front page
                setTimeout(() => {
                    window.location.href = 'frontpage.html';
                }, 1500);
            })
            .catch(error => {
                showMessage('Login failed. Please check your credentials.', 'error');
                console.error('Error:', error);
            });
        

Response:

The response includes detailed information about the user, their role, associated organizations, and feature access.

Response Fields:

• token: JWT authentication token
• full_name: User's full name
• user_id: Unique identifier for the user
• role: User's role in the system (e.g., "admin")
• email: User's email address
• user_details: Detailed information about the user's profile
  • id: User ID
  • email: User's email
  • first_name: User's first name
  • last_name: User's last name
  • photo_file_name: Optional filename for user's photo
  • photo_content_type: Media type of user's photo
  • organizations: List of organizations the user belongs to
    • id: Organization ID
    • name: Organization name
    • subdomain: Organization subdomain
    • custom_domain: Optional custom domain
    • description: HTML description of the organization
    • addresses: Physical addresses associated with the organization
• organization_info: Information about the user's organization
  • permanent_org: Permanent organization details
  • settings: Organization-specific settings
    • transcription_service: Service used for transcription
    • filler_words: Boolean to include/exclude filler words in transcription
    • vocabulary: Custom vocabulary for transcription
    • auto_chaptering: Boolean for automatic chapter creation
    • summary_prompt: Prompt used for generating summaries
    • chaptering_prompt: Prompt used for generating chapters
  • branding: Boolean for custom branding
  • activity: Boolean for activity tracking
  • org_manager_view_all: Permission setting for organization managers
  • export_allowed: Boolean for export permission
  • require_session_passwords: Boolean for session password requirement
  • local_recordings_allowed: Boolean for local recording permission
  • groups: List of group IDs
  • organization_name: Name of the organization
  • organizational_code: Unique code for the organization
  • credits: Available credits
  • maxProjectsAllowed: Maximum number of allowed projects
  • projects: Current number of projects
  • recording_hours: Hours of recordings
• api_version: Version of the API
• create_gallery: Boolean permission for gallery creation

Example Response:

{
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI4NDc2MjkzOTQ4NjMzIiwiaHR0cHM6Ly90aGVpcnN0b3J5LmlvL3Zpc2l0b3ItaWQiOiI3ZmUzMmExOS04NGM1LTQ5MjEtYjUxNy0yOWQ3YzhlNTRmM2EiLCJpYXQiOjE3MzM0ODUyMDF9.AoBg5ub7DvhJxYz8KpLn",
    "full_name": "Jane Smith",
    "user_id": "847629394863",
    "role": "admin",
    "email": "jane.smith@example.com",
    "user_details": {
        "id": 12345,
        "email": "jane.smith@example.com",
        "first_name": "Jane",
        "last_name": "Smith",
        "photo_file_name": null,
        "photo_content_type": null,
        "organizations": [
            {
                "id": 78,
                "name": "Community Archives Project",
                "subdomain": "communityarchives",
                "custom_domain": "",
                "description": "
The Community Archives Project collects and preserves local stories through audio and video interviews.
",
                "addresses": [
                    {
                        "address_line_1": "123 Main Street",
                        "address_line_2": "Suite 405",
                        "city": "Riverdale",
                        "state": "NY",
                        "zipcode": "10463",
                        "country": "US"
                    }
                ]
            },
            {
                "id": 92,
                "name": "Metro Historical Society",
                "subdomain": "metrohistory",
                "custom_domain": "",
                "description": "
The Metro Historical Society works to document and preserve the cultural heritage of our city's diverse communities.
",
                "addresses": [
                    {
                        "address_line_1": "456 Heritage Avenue",
                        "address_line_2": "",
                        "city": "Metro City",
                        "state": "CA",
                        "zipcode": "90210",
                        "country": "US"
                    }
                ]
            }
        ]
    },

    "organization_info": {
        "permanent_org": {
            "export_allowed": true,
            "archive_nbr": "07kp-2341"
        },
        "settings": {
            "transcription_service": "cloudconvert",
            "filler_words": false,
            "vocabulary": ["genealogy", "archives", "cultural heritage"],
            "auto_chaptering": true,
            "summary_prompt": "Create a concise summary of this oral history interview focusing on the key topics, historical events, and personal experiences discussed.",
            "chaptering_prompt": "Divide this interview into logical chapters based on topic changes and significant moments. Each chapter should include a timecode, title, brief summary, and relevant keywords."
        },
        "branding": true,
        "_id": "6ab92cd3e7f14502937654a2",
        "activity": true,
        "org_manager_view_all": true,
        "aviary_export_allowed": true,
        "require_session_passwords": true,
        "local_recordings_allowed": true,
        "groups": [
            "7ac892d3f4e25613ba98765c",
            "8bd903e4g5f36724cb09876d",
            "9ce014f5h6g47835dc10987e"
        ],
        "organization_name": "Community Archives Admin",
        "organizational_code": "ca_admin_854237",
        "created_at": "2023-04-15T14:27:42.519Z",
        "__v": 5,
        "allow_dial_in": true,
        "local_recordings_polyfill": false,
        "credits": 1750000,
        "maxProjectsAllowed": 300,
        "projects": 187,
        "recording_hours": 428,
        "backgroundUrl": "uploads/projectbackgrounds/KpL8sMnO7qRtUvWxYz9A.jpg"
    },
    "api_version": "2.7.4",
    "create_gallery": true
}

Response:

The response is an array of project objects with details about each project.

Response Fields:

• _id: Unique identifier for the project
• name: Name of the project
• description: Description of the project
• creator: ID of the user who created the project
• backgroundUrl: Path to the background image
• displayTitle: Boolean indicating if the title should be displayed
• defaultProjectForOrganization: Boolean indicating if this is the default project
• organization: Organization ID that owns the project
• created_at: Timestamp of when the project was created
• __v: Version number
• view_only_code: Code for view-only access
• view_only_code_created_at: Timestamp when view-only code was created
• member_code: Code for member access
• member_code_created_at: Timestamp when member code was created
• project_manager_code: Code for project manager access
• project_manager_code_created_at: Timestamp when project manager code was created
• projectBackgroundUrl: Full URL to the background image
• folders: Array of folder objects belonging to the project
  • _id: Unique identifier for the folder
  • name: Name of the folder
  • creator: ID of the user who created the folder
  • project: Project ID the folder belongs to
  • defaultFolderForProject: Boolean indicating if this is the default folder
  • created_at: Timestamp of when the folder was created
  • __v: Version number
  • fu: Array of folder user objects
    • _id: Unique identifier for the folder user relationship
    • user: User ID
    • accepted: Boolean indicating if the user accepted the folder invitation
    • creator: Boolean indicating if the user is the creator
    • folder: Folder ID
    • created_at: Timestamp when the relationship was created
    • __v: Version number
• organizationName: Name of the organization the project belongs to
• storiesInProject: Count of stories in the project
• isManager: Boolean indicating if the current user is a manager of this project

Example Response:

[
  {
    "_id": "proj123456789",
    "name": "Community Archives",
    "description": "Archive of local community stories and interviews",
    "creator": "user987654321",
    "backgroundUrl": "uploads/projectbackgrounds/community-archives-bg.jpg",
    "displayTitle": true,
    "defaultProjectForOrganization": false,
    "organization": "org123456789",
    "created_at": "2024-01-15T14:26:14.086Z",
    "__v": 0,
    "view_only_code": "aBcD1234EfGh5i6",
    "view_only_code_created_at": "2024-01-15T14:26:58.682Z",
    "member_code": "jKlM7890nOpQ1r2",
    "member_code_created_at": "2024-01-15T14:26:58.987Z",
    "project_manager_code": "sTuV3456wXyZ7a8",
    "project_manager_code_created_at": "2024-10-15T14:30:21.837Z",
    "projectBackgroundUrl": "https://storage.example.com/uploads/projectbackgrounds/community-archives-bg.jpg?token=abc123",
    "folders": [
      {
        "_id": "fold123456789",
        "name": "Senior Interviews",
        "creator": "user987654321",
        "project": "proj123456789",
        "defaultFolderForProject": false,
        "created_at": "2024-01-20T12:57:05.461Z",
        "__v": 0,
        "fu": [
          {
            "_id": "foldu123456789",
            "user": "user987654321",
            "accepted": true,
            "creator": true,
            "folder": "fold123456789",
            "created_at": "2024-01-20T12:57:05.484Z",
            "__v": 0
          }
        ]
      }
    ],
    "organizationName": "Community Archives Organization",
    "storiesInProject": 32,
    "isManager": true
  },
  {
    "_id": "proj987654321",
    "name": "Oral History Collection",
    "description": "Collection of oral histories from community members",
    "creator": "user123456789",
    "backgroundUrl": "uploads/projectbackgrounds/oral-history-bg.jpg",
    "displayTitle": true,
    "defaultProjectForOrganization": false,
    "organization": "org987654321",
    "created_at": "2024-02-10T19:08:14.209Z",
    "__v": 0,
    "view_only_code": "bCdE2345fGhI6j7",
    "view_only_code_created_at": "2024-02-10T19:36:20.241Z",
    "member_code": "kLmN8901oPqR2s3",
    "member_code_created_at": "2024-02-25T15:50:06.822Z",
    "projectBackgroundUrl": "https://storage.example.com/uploads/projectbackgrounds/oral-history-bg.jpg?token=def456",
    "folders": [],
    "organizationName": "Oral History Foundation",
    "storiesInProject": 18,
    "isManager": false
  }
]

Response:

The response includes an array of organization objects with details about each organization the user has access to.

Response Fields:

• organizations: Array of organization objects, each containing:
  • _id: Unique identifier for the organization
  • activity: Boolean indicating if the organization is active
  • org_manager_view_all: Boolean controlling manager view permissions
  • export_allowed: Boolean for export permission
  • require_session_passwords: Boolean for session password requirement
  • groups: Array of group IDs
  • organization_name: Name of the organization
  • organizational_code: Unique code for the organization
  • created_at: Creation timestamp
  • __v: Version number
  • local_recordings_polyfill: Boolean to enable recording polyfill
  • allow_dial_in: Boolean to allow dial-in functionality
  • local_recordings_allowed: Boolean for local recording permission
  • permanent_org: Object with organization permanence details
  • credits: Available credits
  • backgroundUrl: URL to the organization's background image
  • maxProjectsAllowed: Maximum number of allowed projects
  • projects: Current number of projects
  • recording_hours: Available recording hours
  • branding: Boolean for custom branding
  • settings: Object with organization settings
    • transcription_service: Service used for transcription
    • filler_words: Boolean to include/exclude filler words
    • vocabulary: Array of custom vocabulary words
    • auto_chaptering: Boolean for automatic chapter creation
    • summary_prompt: Prompt for summary generation
    • chaptering_prompt: Prompt for chapter generation
  • users: Array of user objects belonging to the organization

Example Response:

{
  "organizations": [
    {
      "_id": "org123456789",
      "activity": true,
      "org_manager_view_all": true,
      "aviary_export_allowed": true,
      "require_session_passwords": false,
      "groups": ["group1234", "group5678", "group9012"],
      "organization_name": "Community Archives Project",
      "organizational_code": "cap_admin_2023",
      "created_at": "2023-04-15T14:27:42.519Z",
      "__v": 5,
      "local_recordings_polyfill": false,
      "allow_dial_in": true,
      "local_recordings_allowed": true,
      "permanent_org": {
        "export_allowed": true,
        "archive_nbr": "07kp-2341"
      },
      "credits": 1750000,
      "backgroundUrl": "uploads/projectbackgrounds/community-archives-bg.jpg",
      "maxProjectsAllowed": 300,
      "projects": 187,
      "recording_hours": 428,
      "branding": true,
      "settings": {
        "transcription_service": "cloudconvert",
        "filler_words": false,
        "vocabulary": ["oral history", "archives", "cultural heritage"],
        "auto_chaptering": true,
        "summary_prompt": "Create a concise summary of this oral history interview focusing on the key topics, historical events, and personal experiences discussed.",
        "chaptering_prompt": "Divide this interview into logical chapters based on topic changes and significant moments."
      },
      "users": [
        {
          "_id": "user123456",
          "is_verified": false,
          "role": "admin",
          "stories": [],
          "full_name": "Emma Johnson",
          "email": "emma.johnson@example.com",
          "organization": "org123456789",
          "signed_up": "2023-05-12T15:32:47.821Z",
          "__v": 0,
          "create_gallery": true,
          "featureFlags": {
            "enableTwilioVideo": true,
            "localRecordingMimeType": "video/webm;codecs=vp8,opus",
            "disableAutomaticResolutionSwitching": false,
            "autoChaptering": true,
            "_id": "flag123456"
          }
        }
      ]
    }
  ]
}

Response:

The response includes pagination information and an array of story objects with comprehensive details about each recording.

Response Fields:

• page: Current page number
• total: Total number of stories
• items: Array of story objects, each containing details about the recording

Response:

The response is a JSON object containing detailed transcript information, story metadata, and associated media URLs.

Response Fields:

• transcript: Object containing transcript details
  • _id: Unique identifier for the transcript
  • created_at: Timestamp when the transcript was created
  • words: Array of word objects, each containing:
    • start: Start time of the word in seconds
    • end: End time of the word in seconds
    • text: The actual word
  • paragraphs: Array of paragraph objects with speaker and timing information
  • status: Status of the transcript (e.g., "completed")
  • storyId: ID of the associated story
  • updated_at: Timestamp when the transcript was last updated
• story: Object containing story details
  • _id: Unique identifier for the story
  • title: Title of the story
  • author: Information about the story's author/creator
  • record_date: Date when the recording was made
  • duration: Duration of the recording in seconds
  • indexes: Array of index objects containing chapter metadata
  • asyncOperations: Array of processing operations performed on the story
  • Additional metadata about the recording
• videoURL: URL to access the video recording
• participants: Array of participants in the recording
• tags: Array of tags associated with the recording

Example Response (truncated):

{
    "transcript": {
        "_id": "abc123def456ghi789",
        "created_at": "2025-01-27T16:46:48.850Z",
        "words": [
            {
                "start": 1.12,
                "end": 1.44,
                "text": "Super"
            },
            {
                "start": 1.44,
                "end": 1.8,
                "text": "quickly."
            },
            {
                "start": 1.8,
                "end": 2.16,
                "text": "Then"
            },
            // Additional words...
        ],
        "paragraphs": [
            {
                "start": 0,
                "end": 105.6,
                "speaker": "SPEAKER_S1"
            }
        ],
        "status": "completed",
        "storyId": "def456ghi789jkl012",
        "updated_at": "2025-01-27T16:46:48.850Z"
    },
    "story": {
        "_id": "def456ghi789jkl012",
        "title": "Example Recording",
        "record_date": "2025-01-27T16:44:51.289Z",
        "duration": 107,
        // Additional story metadata...
    },
    "videoURL": "https://example.s3.amazonaws.com/uploads/example-id/transcoded.mp4?token=example",
    "participants": [],
    "tags": []
}

Response:

The response is an HTML document containing the transcript with timing data attributes that make it compatible with interactive transcript libraries like Hyperaudio Lite.

Example Response:

<article>
    <section>
        <p>
            <span data-m="0" data-d="0" class="speaker">SPEAKER_S1: </span>
            <span data-m="1120" data-d="320">Super </span>
            <span data-m="1440" data-d="360">quickly. </span>
            <span data-m="1800" data-d="360">Then </span>
            <span data-m="2240" data-d="240">this </span>
            <span data-m="2480" data-d="200">is </span>
            <span data-m="2680" data-d="200">the </span>
            <span data-m="3040" data-d="280">bug </span>
            <span data-m="3320" data-d="320">where </span>
            ...
        </p>
    </section>
</article>

HTML Format Details:

• data-m: Timestamp in milliseconds for when the word begins
• data-d: Duration of the word in milliseconds
• class="speaker": Denotes a speaker change in the transcript

Usage with Hyperaudio Lite:

This HTML format is designed to work with libraries like Hyperaudio Lite to create interactive transcripts where:

• Clicking on a word jumps the audio/video to that timestamp
• Words are highlighted as the audio/video plays
• Searching within the transcript is possible
• Different speakers can be visually distinguished