Skip to main content

​
Quickstart Guide

This guide will help you make your first API call to VidaPlus API. You’ll learn how to install dependencies, authenticate, and interact with the API.
Before you begin, ensure you have Python 3.13 or higher installed on your system.

​
Prerequisites

You’ll need the following installed:
  • Python 3.13 or higher
  • Poetry 2.1.2 (Python package manager)
  • A running instance of VidaPlus API (local or remote)

​
Step 1: Install Poetry

VidaPlus API uses Poetry for dependency management. Install it using pipx: 
pipx install poetry==2.1.2
pipx inject poetry poetry-plugin-shell

​
Step 2: Set Up Python Version

The project requires Python 3.13.2. If you use pyenv for Python version management: 
pyenv local 3.13.2

​
Step 3: Install Dependencies

Clone the repository and install all required dependencies:
1

Install project dependencies

poetry install
This command installs all dependencies specified in pyproject.toml.
2

Activate the virtual environment

poetry shell
This activates the Poetry-managed virtual environment.

​
Step 4: Configure Environment Variables

Create a .env file in the project root with the required configuration:
.env
DATABASE_URL=sqlite+aiosqlite:///database.db
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
Never commit your .env file to version control. Always use strong, randomly generated secret keys in production.

​
Step 5: Start the API Server

Launch the development server using the task command: 
task run
The API will be available at:
  • API: http://localhost:8000
  • Interactive Docs: http://localhost:8000/docs
  • OpenAPI Schema: http://localhost:8000/api/v1/openapi.json
The task run command is equivalent to fastapi dev vidaplus/app.py and provides hot-reloading for development.

​
Step 6: Create Your First User

Before you can authenticate, you need a user account. Let’s create a patient user using the interactive documentation:
1

Open the API docs

Navigate to http://localhost:8000/docs in your browser.
2

Find the POST /pacientes/ endpoint

Scroll to the “Pacientes” section and expand the POST /pacientes/ endpoint.
3

Create a patient

Use the “Try it out” feature with a request body like:
{
  "nome": "João Silva",
  "email": "[email protected]",
  "senha": "securepassword123",
  "telefone": "11999999999",
  "cpf": "12345678901",
  "data_nascimento": "1990-01-15",
  "endereco": "Rua das Flores",
  "numero": "123",
  "bairro": "Centro",
  "cidade": "São Paulo",
  "estado": "SP",
  "cep": "01000000",
  "tipo": "PACIENTE",
  "is_active": true,
  "is_superuser": false
}
In production, user creation would typically require administrator authentication. For initial setup, you may need to create a superuser directly in the database.

​
Step 7: Authenticate and Get Access Token

Now let’s obtain a JWT token for authentication: 
import requests

# Login to get access token
response = requests.post(
    "http://localhost:8000/auth/token/",
    data={
        "username": "[email protected]",  # Use email as username
        "password": "securepassword123"
    },
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

token_data = response.json()
access_token = token_data["access_token"]
token_type = token_data["token_type"]

print(f"Access Token: {access_token}")
print(f"Token Type: {token_type}")

​
Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

​
Step 8: Make Your First Authenticated Request

Use the access token to make authenticated API calls: 
import requests

# Use the token from previous step
headers = {
    "Authorization": f"Bearer {access_token}"
}

# Get list of patients
response = requests.get(
    "http://localhost:8000/pacientes/",
    headers=headers
)

patients = response.json()
print(patients)

​
Response

{
  "pacientes": [
    {
      "id": 1,
      "nome": "João Silva",
      "email": "[email protected]",
      "telefone": "11999999999",
      "cpf": "12345678901",
      "tipo": "PACIENTE",
      "is_active": true
    }
  ]
}

​
Step 9: Refresh Your Token

Tokens expire after 30 minutes by default. Refresh your token before it expires: 
response = requests.post(
    "http://localhost:8000/auth/token/refresh_token",
    headers={"Authorization": f"Bearer {access_token}"}
)

new_token_data = response.json()
new_access_token = new_token_data["access_token"]

​
Next Steps

Congratulations! You’ve successfully: ✅ Installed VidaPlus API and its dependencies
✅ Started the development server
✅ Authenticated and obtained an access token
✅ Made your first authenticated API request

​
Explore More

API Reference

Explore all available endpoints and their parameters

Authentication Guide

Learn more about JWT authentication and security

Installation Details

Advanced installation options including Docker deployment

Guides

Learn about deployment, testing, and contributing

​
Common Issues

  • Verify your email and password are correct
  • Check that the user exists in the database
  • Ensure you’re using the email as the username field
  • Confirm the password was hashed correctly during user creation
Tokens expire after 30 minutes. Use the refresh token endpoint to obtain a new token without re-authenticating.
  • Verify your DATABASE_URL in the .env file is correct
  • Ensure the database file exists (for SQLite) or the database server is running (for PostgreSQL)
  • Check database permissions
  • Ensure you’ve activated the Poetry shell: poetry shell
  • Run poetry install to install all dependencies
  • Verify you’re using Python 3.13+

Build docs developers (and LLMs) love

Get started for freeTalk to us