Documentación

Inicio › API y MCP

API y MCP

Publica microtareas para personas reales, revisa los envíos y consulta tu saldo desde tu código con la API REST, o deja que Claude, ChatGPT, Cursor y tus propios agentes lo hagan a través del servidor MCP.

Servidor MCP

Conecta Claude, ChatGPT, Cursor, Codex o tu propio agente a RapidWorkers. La IA puede consultar precios, publicar microtareas para personas reales y revisar el trabajo, y te muestra el costo antes de cobrar nada.

URL del servidor
https://www.rapidworkers.io/api/mcp/
Transporte
Streamable HTTP
Inicio de sesión
OAuth 2.1 o clave API
Herramientas
22

¿Nuevo en MCP? Descubre qué puede hacer el servidor MCP de RapidWorkers. ¿Prefieres HTTP sin más? La referencia de la API REST está más abajo.

Conecta tu cliente

Las apps compatibles con inicio de sesión abren una ventana de acceso de RapidWorkers la primera vez que las usas. Para las demás, crea una clave API en el panel. Cada configuración indica dónde va la clave: en lugar de YOUR_RAPIDWORKERS_API_KEY o en la variable de entorno RAPIDWORKERS_API_KEY.

Claude (web, escritorio, móvil)

Inicio de sesión con RapidWorkers
Añadir a Claude
  1. Abre Claude, ve a Customize y luego a Connectors, y elige Add custom connector.
  2. Ponle el nombre RapidWorkers y pega https://www.rapidworkers.io/api/mcp/ como URL.
  3. Haz clic en Connect e inicia sesión con tu cuenta de RapidWorkers para aprobar el acceso.

Autenticación

Inicio de sesión con RapidWorkers (OAuth)

Claude, ChatGPT y la mayoría de los clientes de escritorio abren una página de inicio de sesión de RapidWorkers y te piden que apruebes los permisos de abajo. No hay nada que copiar, y la app solo obtiene los permisos que apruebas.

Clave API

Para clientes sin inicio de sesión, scripts y agentes autónomos. Envía la clave como bearer token. Una clave API tiene acceso completo a la cuenta, igual que la API REST.

HTTP
Authorization: Bearer YOUR_RAPIDWORKERS_API_KEY

Permisos (scopes de OAuth)

ScopePermite
account:readLeer tu saldo, tus transacciones y el estado de tu cuenta
jobs:readLeer tus trabajos, encuestas, tareas de IA y sus envíos
jobs:writeCrear, ampliar y cancelar trabajos, encuestas y tareas de IA (gasta saldo)
submissions:reviewAprobar o rechazar envíos y bloquear trabajadores (paga a los trabajadores)
deposit:createCrear enlaces de pago de depósitos para que pagues tú
  • Revoca una clave API o desconecta una app con sesión iniciada en cualquier momento desde la página Gestión de API de tu panel. El acceso se corta de inmediato.
  • Nunca pongas una clave en una URL ni en un query string. Envíala solo en la cabecera Authorization y no subas al control de versiones los archivos de configuración que contengan una clave.

Herramientas

22 herramientas. Las herramientas de solo lectura nunca modifican nada. Las marcadas como Gasta dinero cobran de tu saldo o pagan a los trabajadores, y los clientes que respetan las indicaciones de las herramientas te piden confirmación antes de ejecutarlas.

Cuenta y plataforma

HerramientaQué hacePermisoAcceso
get_accountConsultar la cuentaSaldo, estado de los depósitos, acceso a tareas de IA y tasa de comisión.Permiso: account:readSolo lectura
get_platform_infoConsultar reglas y opciones de la plataformaLímites, tarifas, categorías de trabajos, tipos de trabajos predefinidos, tipos de tareas de IA, opciones del creador de encuestas y códigos de país.Permiso: Cualquier conexiónSolo lectura
list_transactionsListar transaccionesLos últimos depósitos, cargos, reembolsos y pagos.Permiso: account:readSolo lectura
get_deposit_linkCrear enlace de depósitoUn enlace de pago con tarjeta o criptomonedas para que una persona pague (mínimo $20).Permiso: deposit:createModifica datos

Trabajos, encuestas y tareas de IA

HerramientaQué hacePermisoAcceso
preview_job_costPrevisualizar el costo del trabajoCosto exacto (pago × trabajadores + comisión + fijación) y un id de cotización, antes de cobrar nada.Permiso: jobs:readSolo lectura
create_jobCrear trabajoPublica una microtarea personalizada para personas reales, con una imagen opcional generada con IA; el costo se cobra del saldo.Permiso: jobs:writeGasta dinero
create_prefilled_jobCrear trabajo predefinidoTrabajos de un solo enlace para tareas comunes como me gusta, seguidores, compartidos o reseñas.Permiso: jobs:writeGasta dinero
create_surveyCrear encuestaCrea un cuestionario que responden personas reales en RapidWorkers, con preguntas de filtro y controles de calidad; el costo se cobra del saldo.Permiso: jobs:writeGasta dinero
create_ai_taskCrear tarea de datos para IARecopila fotos, audio, video o texto de personas reales para entrenar IA, con una imagen de ejemplo opcional generada con IA.Permiso: jobs:writeGasta dinero
request_ai_task_accessSolicitar acceso a tareas de IAPide al equipo de RapidWorkers que habilite las tareas de datos para IA en la cuenta.Permiso: jobs:writeModifica datos
list_jobsListar trabajosTus trabajos, encuestas o tareas de IA con su estado, progreso y envíos pendientes.Permiso: jobs:readSolo lectura
get_jobConsultar un trabajoTodos los detalles de un trabajo, una encuesta o una tarea de IA.Permiso: jobs:readSolo lectura
extend_jobAñadir trabajadores a un trabajoAñade más plazas de trabajadores a un trabajo; el costo adicional se cobra del saldo.Permiso: jobs:writeGasta dinero
cancel_jobCancelar trabajoDetiene un trabajo y reembolsa el presupuesto no utilizado (los trabajos activos tienen una tarifa de $0.20).Permiso: jobs:writeGasta dinero

Revisión y trabajadores

HerramientaQué hacePermisoAcceso
list_submissionsListar envíosEnvíos de los trabajadores con el texto de la prueba, enlaces a imágenes y estadísticas del trabajador, o respuestas de encuestas con lo que contestaron y su puntuación de calidad.Permiso: jobs:readSolo lectura
get_survey_resultsConsultar resultados de la encuestaRecuentos, porcentajes, promedios, NPS y muestras de texto de cada pregunta de una encuesta.Permiso: jobs:readSolo lectura
approve_submissionAprobar envíoAprueba un envío y paga al trabajador, con una propina opcional.Permiso: submissions:reviewGasta dinero
reject_submissionRechazar envíoRechaza un envío con un motivo que el trabajador puede ver.Permiso: submissions:reviewModifica datos
approve_all_pendingAprobar todos los envíos pendientesAprueba y paga de una vez todos los envíos pendientes de un trabajo, o solo las respuestas de encuesta con buena puntuación de calidad.Permiso: submissions:reviewGasta dinero
block_workerBloquear trabajadorImpide que un trabajador acepte tus trabajos; sus envíos pendientes se rechazan.Permiso: submissions:reviewModifica datos
unblock_workerDesbloquear trabajadorPermite que un trabajador bloqueado vuelva a aceptar tus trabajos.Permiso: submissions:reviewModifica datos
list_blocked_workersListar trabajadores bloqueadosLos trabajadores que has bloqueado.Permiso: jobs:readSolo lectura

Imágenes generadas con IA

create_job, create_prefilled_job, create_survey y create_ai_task aceptan un image_prompt opcional (de 20 a 4,000 caracteres) que describe una imagen para mostrar a los trabajadores junto a las instrucciones. RapidWorkers lo convierte, junto con los detalles del trabajo, en un brief de diseño detallado y genera la imagen con IA sin costo adicional. Los trabajos la muestran con sus imágenes, las encuestas con su introducción, y las tareas de IA la adjuntan como ejemplo de lo que hay que enviar.

Hasta que se adjunta la imagen, el trabajo espera como pending_image, oculto para los trabajadores, y luego se publica automáticamente, normalmente en uno o dos minutos. Si la generación falla, se publica sin la imagen. get_job la devuelve en image_urls, o en reference_file_urls para las tareas de IA.

Encuestas

create_survey publica un cuestionario que las personas responden en RapidWorkers: preguntas de opción, lista desplegable, valoración (estrellas, grado de acuerdo o NPS), matriz, clasificación, texto, número, fecha y consentimiento, además de bloques de texto, hasta 5 preguntas de filtro, lógica de visualización con show_if y controles de atención de la plataforma. Las preguntas se identifican como q_1, q_2, etc., según su posición. El pago es de al menos $0.50 por respuesta, y a quienes no pasan el filtro no se les paga.

Las demás herramientas reciben kind: "survey". list_submissions devuelve cada respuesta con lo contestado, su puntuación de calidad y su banda. approve_all_pending puede aprobar solo la banda good. get_survey_results devuelve los totales de cada pregunta.

Recursos y prompts

Los recursos son documentos de solo lectura que un cliente puede cargar en la conversación. Los prompts son flujos de trabajo listos para usar que aparecen como sugerencias de prompts o comandos con barra en los clientes que los admiten.

Recursos

URIContenido
rapidworkers://platformReglas y opciones de la plataforma (application/json)
rapidworkers://guideGuía rápida para agentes (text/markdown)

Prompts

PromptQué hace
post_social_boostImpulsar una publicación en redesElige un tipo de trabajo predefinido, previsualiza el costo y publícalo.
review_pending_submissionsRevisar envíos pendientesCompara las pruebas con las instrucciones y aprueba o rechaza cada una.
collect_training_dataRecopilar datos de entrenamiento para IAPlanifica y publica una tarea de recopilación de datos para IA.

Reglas y errores

El servidor MCP sigue las mismas reglas que el sitio web y la API REST.

  • $0.05pago mínimo por tarea ($0.10 en tareas de datos para IA, $0.50 por respuesta de encuesta)
  • 10trabajadores como mínimo por trabajo
  • $20depósito mínimo, necesario una sola vez antes de publicar
  • Costopago × trabajadores + comisión, más $10 por fijar un trabajo

Confirma antes de gastar

  1. preview_job_cost devuelve el total exacto, si tu saldo lo cubre y un quote_id válido durante 10 minutos.
  2. La IA te muestra el total y espera tu aprobación.
  3. La herramienta de creación se ejecuta con ese quote_id, confirm: true y una idempotency_key. Si reintentas con la misma clave, recibes el primer resultado en lugar de publicar el trabajo dos veces.
JSON
{
  "quote_id": "<quote_id from preview_job_cost>",
  "confirm": true,
  "idempotency_key": "signup-test-2026-11-07"
}

Errores

Los errores de las herramientas llegan como un resultado normal con isError: true, para que el modelo pueda leer el mensaje y corregir la llamada.

SituaciónQué recibes
Sin clave ni sesión iniciada, o caducadasHTTP 401 con una cabecera WWW-Authenticate que apunta a los metadatos de inicio de sesión. Los clientes OAuth inician sesión a partir de ella.
Un permiso que no aprobasteError de la herramienta: "This connection lacks the jobs:write permission; reconnect and approve it." (a esta conexión le falta el permiso jobs:write; vuelve a conectarla y apruébalo).
Pago, cantidad o saldo por debajo de las reglasError de la herramienta que indica cómo corregirlo, como "Pay rate must be at least $0.05", o cuánto falta y una referencia a get_deposit_link.
La cotización caducó o el trabajo cambió después de la vista previaError de la herramienta. Vuelve a llamar a preview_job_cost y confirma el nuevo total.
Demasiadas solicitudesLos límites son por cuenta, no por clave: 1,000 solicitudes por hora compartidas por todas tus claves API (MCP y API REST juntas), y otras 1,000 por hora compartidas por todas las apps con sesión iniciada. Espera y vuelve a intentarlo.

Código para agentes

Llama al servidor desde tu propio agente a través de la API de un modelo, o pruébalo desde la terminal. Guarda la clave API en una variable de entorno, como RAPIDWORKERS_API_KEY, y exige aprobación para las herramientas que gastan dinero.

API de Claude (Python)

python
import os
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{
        "type": "url",
        "url": "https://www.rapidworkers.io/api/mcp/",
        "name": "rapidworkers",
        "authorization_token": os.environ["RAPIDWORKERS_API_KEY"],
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "rapidworkers"}],
    messages=[{
        "role": "user",
        "content": "Get 20 people to test the signup flow at https://example.com and report bugs. Show me the cost before posting.",
    }],
)
print(response.content)

Lee la clave de la variable de entorno RAPIDWORKERS_API_KEY. Primero asígnale tu clave API.

API Responses de OpenAI (configuración de la herramienta)

json
{
  "type": "mcp",
  "server_label": "rapidworkers",
  "server_url": "https://www.rapidworkers.io/api/mcp/",
  "headers": {
    "Authorization": "Bearer YOUR_RAPIDWORKERS_API_KEY"
  },
  "require_approval": "always"
}

MCP Inspector (prueba desde la terminal)

bash
npx @modelcontextprotocol/inspector --cli https://www.rapidworkers.io/api/mcp/ \
  --transport http --header "Authorization: Bearer $RAPIDWORKERS_API_KEY" --method tools/list

Lee la clave de la variable de entorno RAPIDWORKERS_API_KEY. Primero asígnale tu clave API.

Cabecera de Autenticación

Incluye tu clave API en cada solicitud usando la cabecera X-API-Key:

HTTP
X-API-Key: your_api_key_here

Límite de tasa: 1,000 solicitudes por hora por cuenta, compartidas por todas tus claves API

Endpoints

Endpoints Estándar

Crea un nuevo trabajo/campaña con detalles especificados. Requiere tipo de contenido multipart/form-data. Establece approve_once_full en true para aprobar automáticamente todas las presentaciones y pagar a los trabajadores una vez que el trabajo alcance su total de disponibilidades.

Content-Type:multipart/form-data

titlestringobligatorio
descriptionstringobligatorio
pay_ratedecimalobligatorio
total_availabilitiesintegerobligatorio
proof_required_descriptionstringobligatorio
categorystringobligatorio
sub_categorystring
campaign_imagesfile

repite el campo para enviar hasta 10 imágenes; JPG, PNG o WEBP, máx. 1 MB cada una

campaign_imagefile

una sola imagen; cuenta dentro de las 10

image_promptstring

de 20 a 4000 caracteres. Una descripción detallada de una imagen que generamos con IA y añadimos al trabajo después de crearlo; cuenta dentro de las 10

countriesarray

Omítelo para incluir todos los países

excluded_countriesarray

Solo si está abierto a todos los países: códigos ISO que quieres excluir, p. ej., IN, BD

approve_once_fullboolean

predeterminado: false. Si es true, todos los envíos se aprueban automáticamente y se paga a los trabajadores cuando el trabajo completa todas sus plazas (total_availabilities)

python
import requests

# Create a job without image
job_data = {
    "title": "Complete a Survey",
    "description": "Fill out our 5-minute customer satisfaction survey",
    "pay_rate": "2.50",
    "total_availabilities": "100",
    "proof_required_description": "Submit a screenshot of the completion page",
    "category": "Survey",
    "sub_category": (None, "Customer Feedback"),
    "countries": (None, '["US", "CA", "GB"]'),  # Omit to include all countries
}
response = requests.post(
    "https://api.rapidworkers.io/jobs/add",
    headers={"X-API-Key": "your_api_key_here"},
    files=job_data
)
job = response.json()
print(f"Job created: {job['job']['public_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job": {
    "public_id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Test Job",
    "status": "Active",
    "pay_rate": "5.00",
    "total_availabilities": 10
  },
  "deduction_details": {
    "total_cost": "50.00",
    "commission": "5.00",
    "total_deducted": "55.00",
    "new_balance": "945.00"
  }
}

400—Datos no válidos o saldo insuficiente

401—Clave API no válida o ausente

403—Trabajo rechazado por la verificación de legitimidad

Recupera el saldo actual de tu cuenta.

Content-Type:application/json

JSON
{} // Empty body
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/account/get_balance",
    headers={"X-API-Key": "your_api_key_here"}
)
print(f"Balance: {response.json()['balance']}")
JSON
// 200 OK
{
  "balance": "1000.00"
}

401—Clave API no válida o ausente

404—Usuario no encontrado

Aprueba el envío de un trabajador para tu campaña.

Parámetros de Ruta

campaign_idUUID
submission_idinteger

Content-Type:application/json

JSON
{
  "notes": "Great work!", // Optional
  "tip": "2.00" // Optional: $0.01-$50.00 from your balance, paid to the worker in full with no fee
}
python
import requests

campaign_id = "your_campaign_public_id"
submission_id = 456

response = requests.post(
    f"https://api.rapidworkers.io/api/campaigns/{campaign_id}/submissions/{submission_id}/approve/",
    headers={"X-API-Key": "your_api_key_here"},
    json={"notes": "Great work!"}
)
print(f"Submission approved: {response.json()}")
JSON
// 200 OK
{
  "success": true,
  "message": "Submission approved successfully",
  "submission": {
    "id": 123,
    "userId": 12345, // Worker public ID
    "userName": "Maria G.", // First name and last-name initial; employers never see a worker's email or full name
    "status": "Approved",
    "amount_paid": "5.00"
  }
}

400—Envío ya procesado, fondos insuficientes o propina no válida

403—Esta campaña no es tuya

404—Envío no encontrado

Rechaza el envío de un trabajador con una razón.

Parámetros de Ruta

campaign_idUUID
submission_idinteger

Content-Type:application/json

JSON
{
  "notes": "Does not meet requirements" // Required
}
python
import requests

campaign_id = "your_campaign_public_id"
submission_id = 456

response = requests.post(
    f"https://api.rapidworkers.io/api/campaigns/{campaign_id}/submissions/{submission_id}/reject/",
    headers={"X-API-Key": "your_api_key_here"},
    json={"notes": "Screenshot does not show completion page"}
)
print(f"Submission rejected: {response.json()}")
JSON
// 200 OK
{
  "success": true,
  "message": "Submission rejected",
  "submission": {
    "id": 123,
    "userId": 12345, // Worker public ID
    "userName": "Maria G.", // First name and last-name initial; employers never see a worker's email or full name
    "status": "Rejected",
    "notes": "Does not meet requirements"
  }
}

400—Falta el motivo del rechazo

403—Esta campaña no es tuya

404—Envío no encontrado

Aprueba todos los envíos pendientes de una campaña a la vez.

Parámetros de Ruta

campaign_idUUID

Content-Type:application/json

JSON
{
  "notes": "Bulk action notes" // Optional
}
python
import requests

campaign_id = "your_campaign_public_id"

# Bulk approve all pending
response = requests.post(
    f"https://api.rapidworkers.io/api/campaigns/{campaign_id}/submissions/bulk_action/",
    headers={"X-API-Key": "your_api_key_here"},
    json={"notes": "All submissions verified"}
)
print(f"Bulk action result: {response.json()}")
JSON
// 200 OK
{
  "success": true,
  "message": "All submissions approved successfully.",
  "submissions": [
    { "id": 123, "status": "Approved", "userName": "Maria G." },
    { "id": 124, "status": "Approved", "userName": "Ken T." }
  ]
}

403—Esta campaña no es tuya

404—No hay envíos pendientes

Recupera todas las campañas del usuario autenticado, con filtrado opcional por estado.

statusstring

"Active", "Pending", "Completed", "Canceled"

languagestring

predeterminado: "en"

python
import requests

# List all campaigns
response = requests.get(
    "https://api.rapidworkers.io/api/campaigns/",
    headers={"X-API-Key": "your_api_key_here"}
)
campaigns = response.json()
for campaign in campaigns["results"]:
    print(f"{campaign['jobTitle']} - {campaign['jobStatus']}")

# Filter by status
response = requests.get(
    "https://api.rapidworkers.io/api/campaigns/?status=Active",
    headers={"X-API-Key": "your_api_key_here"}
)
JSON
// 200 OK
[
  {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "jobTitle": "Complete a Survey",
    "jobCategory": "Survey",
    "jobPay": "2.50",
    "jobLocation": "In",
    "jobCreatedAt": "2025-01-15T10:30:00Z",
    "jobStatus": "Active",
    "jobInstancesCompleted": 45,
    "jobTotalAvailabilities": 100,
    "jobSuccessRate": "40%",
    "description": "Fill out our customer satisfaction survey",
    "canceled": false,
    "remainingAvailabilities": 55,
    "pendingSubmissions": 12,
    "approvedSubmissions": 40,
    "rejectedSubmissions": 5
  }
]

401—Clave API no válida o ausente

Recupera información detallada sobre una campaña específica incluyendo conteos de envíos y disponibilidad restante.

Parámetros de Ruta

campaign_idUUID
languagestring

predeterminado: "en"

python
import requests

campaign_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(
    f"https://api.rapidworkers.io/api/campaigns/detail/{campaign_id}/",
    headers={"X-API-Key": "your_api_key_here"}
)
campaign = response.json()
print(f"Remaining slots: {campaign['remaining_availabilities']}")
print(f"Pending: {campaign['pending_submissions']}")
JSON
// 200 OK
{
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "jobTitle": "Complete a Survey",
  "jobCategory": "Survey",
  "jobPay": "2.50",
  "jobLocation": "In",
  "jobCreatedAt": "2025-01-15T10:30:00Z",
  "jobStatus": "Active",
  "jobInstancesCompleted": 45,
  "jobTotalAvailabilities": 100,
  "jobSuccessRate": "40%",
  "description": "Fill out our customer satisfaction survey",
  "canceled": false,
  "remainingAvailabilities": 55,
  "pendingSubmissions": 12,
  "approvedSubmissions": 40,
  "rejectedSubmissions": 5
}

401—Clave API no válida o ausente

403—Esta campaña no es tuya

404—Campaña no encontrada

Recupera todos los envíos de una campaña específica con metadatos del trabajador, filtrado opcional por estado y paginación.

Parámetros de Ruta

campaign_idUUID
statusstring

"Pending", "Approved", "Rejected"

searchstring

busca por nombre del trabajador

pageinteger

predeterminado: 1

rowsPerPageinteger

predeterminado: 1000

languagestring

predeterminado: "en"

python
import requests

campaign_id = "123e4567-e89b-12d3-a456-426614174000"

# List all submissions
response = requests.get(
    f"https://api.rapidworkers.io/api/campaigns/{campaign_id}/submissions/",
    headers={"X-API-Key": "your_api_key_here"}
)
data = response.json()
for sub in data["results"]["submissions"]:
    print(f"#{sub['submissionId']} - {sub['status']} - Age: {sub['worker_account_age_days']}d")

# Filter pending only
response = requests.get(
    f"https://api.rapidworkers.io/api/campaigns/{campaign_id}/submissions/?status=Pending",
    headers={"X-API-Key": "your_api_key_here"}
)
JSON
// 200 OK
{
  "count": 45,
  "next": null,
  "previous": null,
  "results": {
    "submissions": [
      {
        "submissionId": 123,
        "userId": "abc-def-123",
        "userName": "Maria G.", // First name and last-name initial; employers never see a worker's email or full name
        "userAvatar": "https://...",
        "campaignId": "123e4567-e89b-12d3-a456-426614174000",
        "campaignTitle": "Complete a Survey",
        "status": "Pending",
        "country_name": "United States",
        "submittedAt": "2025-01-16T14:30:00Z",
        "proof_text": "Completed the survey as requested",
        "images": [
          { 
            "id": "img_1", 
            "url": "https://...", 
            "thumbnailUrl": "https://..." 
          }
        ],
        "notes": null,
        "workerAccountAgeDays": 120,
        "workerApprovalRate": "85%",
        "workerTotalCompleted": 47
      }
    ],
    "pagination": {
      "totalCount": 45,
      "pageCount": 1,
      "currentPage": 1,
      "rowsPerPage": 1000
    }
  }
}

401—Clave API no válida o ausente

403—Esta campaña no es tuya

404—Campaña no encontrada

Bloquea a un trabajador para que no pueda enviar pruebas a ninguna de tus campañas. Los trabajadores bloqueados no verán tus campañas en su lista de trabajos.

Content-Type:application/json

JSON
{
  "worker_id": 12345 // Worker public ID
}
python
import requests

worker_id = 12345

response = requests.post(
    "https://api.rapidworkers.io/api/workers/block/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={"worker_id": worker_id}
)
print(f"Worker blocked: {response.json()}")
JSON
// 201 Created
{
  "success": true,
  "message": "Worker blocked successfully",
  "worker_id": 12345
}

400—Falta worker_id, intentaste bloquearte a ti mismo o el trabajador ya está bloqueado

401—Clave API no válida o ausente

404—Trabajador no encontrado

Desbloquea a un trabajador previamente bloqueado, permitiéndole ver y enviar pruebas a tus campañas nuevamente.

Content-Type:application/json

JSON
{
  "worker_id": 12345
}
python
import requests

worker_id = 12345

response = requests.post(
    "https://api.rapidworkers.io/api/workers/unblock/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={"worker_id": worker_id}
)
print(f"Worker unblocked: {response.json()}")
JSON
// 200 OK
{
  "success": true,
  "message": "Worker unblocked successfully",
  "worker_id": 12345
}

400—Falta worker_id o el trabajador no está bloqueado

401—Clave API no válida o ausente

404—Trabajador no encontrado

Recupera la lista de todos los trabajadores que has bloqueado.

Solicitud
No se necesita cuerpo de solicitud.
python
import requests

response = requests.get(
    "https://api.rapidworkers.io/api/workers/blocked/",
    headers={"X-API-Key": "your_api_key_here"}
)
blocked = response.json()
for worker in blocked:
    print(f"Blocked: {worker['worker_name']} (ID: {worker['worker_id']})")
JSON
// 200 OK
[
  {
    "worker_id": 12345,
    "worker_name": "Maria G.", // First name and last-name initial
    "blocked_at": "2025-01-15T10:30:00Z"
  }
]

401—Clave API no válida o ausente

Crea una encuesta que los trabajadores responden en RapidWorkers: preguntas de opción, valoración, NPS, matriz, clasificación, texto, número y fecha, con preguntas filtro, lógica de visualización y comprobaciones de atención opcionales. El pago mínimo es $0.50 por respuesta. A los trabajadores descartados no se les paga. Todos los problemas de las preguntas se indican en una sola respuesta.

Content-Type:application/json

JSON
{
  "title": "Car owner survey", // Required, up to 200 characters
  "description": "A few questions about your car. It takes about 3 minutes.", // Required: the intro workers read (up to 5,000 characters)
  "pay_rate": "0.50", // Required (minimum: 0.50 per response)
  "total_availabilities": 200, // Required (10-20000); "quantity" works too
  "length_in_minutes": 3, // Optional: estimated from the questions when left out
  "countries": ["US", "GB"], // Required. ["All"] for every country, or ISO codes like ["US", "GB"]
  "excluded_countries": [], // Optional, only with ["All"]
  "audience": { "min_age": 18, "max_age": 65, "native_languages": ["en"] }, // Optional: also genders, education, occupations (codes in /api/platform/info/ under survey_builder)
  "settings": { "block_paste": false }, // Optional: true stops pasting into text answers
  "image_prompt": "A friendly illustration of a driver answering a short survey on a phone", // Optional: one image we generate with AI and show with the intro
  "questions": [ // Required: 1-60 items, at most 50 questions. Keys are q_1, q_2, ... by position (text blocks count)
    { "type": "single_choice", "label": "Do you drive at least once a week?", "options": ["Yes", "No"],
      "screener": true, "disqualify": ["No"] }, // Screening questions come first (up to 5); screened-out workers are not paid
    { "type": "rating", "label": "How likely are you to recommend your car brand?", "scale": { "preset": "nps" } },
    { "type": "long_text", "label": "What would make you recommend it?", "max_length": 1000,
      "show_if": [{ "question": "q_2", "operator": "lte", "value": 6 }] }, // Shown only when the answer to q_2 is 6 or less
    { "type": "multiple_choice", "label": "Which features matter most?", "options": ["Price", "Safety", "Comfort"],
      "allow_other": true, "none_option": "None of these", "max_choices": 2, "randomize_options": true },
    { "type": "matrix", "label": "How much do you agree?", "rows": ["It is reliable", "It is cheap to run"],
      "scale": { "preset": "agree_5" } }, // Presets: stars_5, agree_5, agree_7, nps (rating only) or custom (min, max, min_label, max_label)
    { "type": "attention_check", "template": "select_option" } // Templates: select_option, agree_scale, nonsense_statement
    // type: single_choice | multiple_choice | dropdown | rating | matrix | ranking | short_text | long_text
    //       | number | date | consent | statement | attention_check
  ]
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/custom-surveys/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "title": "Car owner survey",
        "description": "A few questions about your car. It takes about 3 minutes.",
        "pay_rate": "0.50",
        "total_availabilities": 200,
        "countries": ["US", "GB"],
        "questions": [
            {"type": "single_choice", "label": "Do you drive at least once a week?",
             "options": ["Yes", "No"], "screener": True, "disqualify": ["No"]},
            {"type": "rating", "label": "How likely are you to recommend your car brand?",
             "scale": {"preset": "nps"}},
            {"type": "long_text", "label": "What would make you recommend it?",
             "show_if": [{"question": "q_2", "operator": "lte", "value": 6}]},
            {"type": "attention_check", "template": "select_option"}
        ]
    }
)
survey = response.json()
print(f"Survey created: {survey['task_id']}")
JSON
// 201 Created
{
  "message": "Survey created successfully",
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active", // "pending_review" during moderation, "pending_image" while its image is generated
  "survey": { "taskPublicId": "123e4567-...", "title": "Car owner survey", "status": "Active", "questionCount": 6, "lengthInMinutes": 3 }
}

// 400 when the questions are not valid: every problem is listed
{
  "error": "Question 4: add 2 to 20 options (and 1 more problem)",
  "code": "invalid_survey",
  "details": [{ "question": "q_4", "field": "options", "message": "Question 4: add 2 to 20 options" }, ...]
}

// Cancel, extend and review responses with the AI-task endpoints and this task_id:
// /api/ai-tasks/{task_id}/cancel/, /extend/, /submissions/{submission_id}/approve/, /reject/ and /submissions/bulk_approve/

400—Encuesta no válida (cada problema aparece en details), saldo insuficiente o la cuenta no tiene ningún depósito

401—Clave API no válida o ausente

409—La cotización de X-Quote-Id caducó o no corresponde a esta encuesta

Lista tus encuestas, de la más reciente a la más antigua, con el número de respuestas, los niveles de calidad y el tiempo mediano de respuesta.

pageinteger

predeterminado: 1

page_sizeinteger

predeterminado: 50, máx. 100

python
import requests

response = requests.get(
    "https://api.rapidworkers.io/api/custom-surveys/mine/",
    headers={"X-API-Key": "your_api_key_here"}
)
for survey in response.json()["results"]:
    print(survey["title"], survey["counts"]["pending"], "pending")
JSON
// 200 OK, newest first
{
  "count": 3,
  "results": [
    {
      "taskPublicId": "123e4567-e89b-12d3-a456-426614174000",
      "taskType": "custom_survey",
      "title": "Car owner survey",
      "status": "Active",
      "pay": "0.50",
      "lengthInMinutes": 3,
      "questionCount": 6,
      "totalAvailabilities": 200,
      "completedCount": 48,
      "slotsOpen": 150,
      "inProgress": 2,
      "countries": ["US", "GB"],
      "createdAt": "2026-11-09T10:00:00Z",
      "counts": { "started": 61, "screenedOut": 11, "submitted": 48, "pending": 20, "approved": 26, "rejected": 2, "autoRejected": 1 },
      "quality": { "good": 40, "check": 5, "likelyBad": 1 },
      "medianSeconds": 174,
      "referenceFiles": [{ "id": 7, "name": "image.png", "contentType": "image/png", "size": 182044, "url": "https://..." }] // The image made from image_prompt, if any
    }
  ]
}

401—Clave API no válida o ausente

Obtiene una de tus encuestas con sus preguntas (claves, ids de opciones, filtros y lógica de visualización), el público, los ajustes y el número de respuestas.

Parámetros de Ruta

survey_idUUID
Solicitud
Sin parámetros
python
import requests

survey_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(
    f"https://api.rapidworkers.io/api/custom-surveys/{survey_id}/",
    headers={"X-API-Key": "your_api_key_here"}
)
survey = response.json()
for question in survey["questions"]:
    print(question["key"], question["label"])
JSON
// 200 OK: the list fields above, plus
{
  "taskPublicId": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Car owner survey",
  "status": "Active",
  "description": "A few questions about your car. It takes about 3 minutes.",
  "reservedAmount": "115.00",
  "paidOutAmount": "13.00",
  "questions": [
    {
      "key": "q_1",
      "type": "single_choice",
      "label": "Do you drive at least once a week?",
      "required": true,
      "page": 1,
      "screener": true,
      "options": [{ "id": "o1", "label": "Yes" }, { "id": "o2", "label": "No" }],
      "disqualify": ["o2"],
      "showIf": []
    },
    {
      "key": "q_3",
      "type": "long_text",
      "label": "What would make you recommend it?",
      "page": 2,
      "showIf": [{ "question": "q_2", "operator": "lte", "value": 6, "questionLabel": "How likely are you to recommend your car brand?", "valueLabel": "6" }]
    }
  ],
  "audience": { "minAge": 18, "maxAge": 65, "genders": [], "nativeLanguages": ["en"], "education": [], "occupations": [] },
  "settings": { "blockPaste": false, "reservationMinutes": null },
  "canEdit": false,
  "editBlockedReason": "has_responses"
}

401—Clave API no válida o ausente

404—Encuesta no encontrada

Devuelve los resultados de una encuesta por pregunta: recuentos y porcentajes de respuestas, medias, NPS, clasificaciones, rangos numéricos y las últimas respuestas escritas, además del embudo de respuestas y los niveles de calidad.

Parámetros de Ruta

survey_idUUID
includestring

"valid" = pendientes y aprobados (predeterminado); "approved"; "all" añade los rechazados

python
import requests

survey_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(
    f"https://api.rapidworkers.io/api/custom-surveys/{survey_id}/results/",
    headers={"X-API-Key": "your_api_key_here"},
    params={"include": "valid"}
)
for question in response.json()["questions"]:
    print(question["key"], question["label"], question["answered"], "answered")
JSON
// 200 OK. Screened-out workers never count as responses
{
  "survey": { "taskPublicId": "123e4567-...", "title": "Car owner survey", "status": "Active", "totalAvailabilities": 200 },
  "include": "valid",
  "funnel": { "started": 61, "screenedOut": 11, "submitted": 48, "pending": 20, "approved": 26, "rejected": 2, "autoRejected": 1 },
  "timing": { "medianSeconds": 174, "effectiveHourlyPay": "10.34" },
  "quality": { "good": 40, "check": 5, "likelyBad": 1 },
  "questions": [
    {
      "key": "q_2", "type": "rating", "label": "How likely are you to recommend your car brand?", "answered": 46, "skipped": 0,
      "distribution": [{ "value": 10, "count": 18, "percent": 39.1 }],
      "mean": 7.9, "median": 8,
      "nps": { "score": 24, "promoters": 22, "passives": 13, "detractors": 11 }
    },
    {
      "key": "q_4", "type": "multiple_choice", "label": "Which features matter most?", "answered": 46, "skipped": 0,
      "options": [{ "id": "o2", "label": "Safety", "count": 31, "percent": 67.4 }],
      "other": { "count": 3, "samples": ["Boot space"] }
    },
    {
      "key": "q_3", "type": "long_text", "label": "What would make you recommend it?", "answered": 11, "skipped": 35,
      "total": 11, "samples": [{ "submissionId": 912, "text": "Cheaper servicing and a longer warranty." }]
    }
  ]
}

401—Clave API no válida o ausente

403—Esta encuesta no es tuya

404—Encuesta no encontrada

Lista las respuestas de una encuesta, de la más reciente a la más antigua, con cada contestación como texto, la puntuación, el nivel y las alertas de calidad, y si se rechazó automáticamente. Filtra por estado y nivel de calidad.

Parámetros de Ruta

survey_idUUID
statusstring

"pending", "approved", "rejected" o "all"

bandstring

banda de calidad: "good", "check" o "likely_bad"

pageinteger

predeterminado: 1

page_sizeinteger

predeterminado: 25, máx. 100

python
import requests

survey_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(
    f"https://api.rapidworkers.io/api/custom-surveys/{survey_id}/responses/",
    headers={"X-API-Key": "your_api_key_here"},
    params={"status": "pending", "band": "likely_bad"}
)
for row in response.json()["results"]:
    print(row["submissionId"], row["qualityScore"], [flag["code"] for flag in row["qualityFlags"]])
JSON
// 200 OK, newest first
{
  "count": 48,
  "page": 1,
  "pageSize": 25,
  "results": [
    {
      "submissionId": 912,
      "workerId": 10457, // The worker_id that /api/workers/block/ takes
      "status": "Pending",
      "autoRejected": false,
      "reasonCode": "", // attention_failed, too_fast or duplicate_device when rejected automatically
      "createdAt": "2026-11-09T11:02:13Z",
      "durationSeconds": 181,
      "country": "United States",
      "qualityScore": 80,
      "qualityBand": "good", // good (70-100), check (40-69) or likely_bad (under 40)
      "qualityFlags": [{ "code": "pasted_text", "severity": "moderate", "detail": "Most of the answer to Q3 was pasted", "question": "q_3" }],
      "answers": [
        { "key": "q_1", "type": "single_choice", "label": "Do you drive at least once a week?", "value": "o1", "display": "Yes" },
        { "key": "q_5", "type": "matrix", "label": "How much do you agree?", "value": { "r1": 4, "r2": 2 }, "display": "It is reliable: 4\nIt is cheap to run: 2" }
      ]
    }
  ]
}

// Approve or reject a response with /api/ai-tasks/{survey_id}/submissions/{submissionId}/approve/ or /reject/

401—Clave API no válida o ausente

403—Esta encuesta no es tuya

404—Encuesta no encontrada

Crea una tarea de datos de IA (recopilación de imágenes, video, audio o texto, etiquetado). Los trabajadores suben archivos directamente a un almacenamiento privado; tú revisas y apruebas cada envío. Acepta JSON, o multipart/form-data al adjuntar imágenes de referencia.

Content-Type:application/json

JSON
{
  "task_type": "image_collection", // Required: image_collection | video_collection | audio_collection | text_collection | custom_data_collection
  "capture_mode": "both", // Optional, audio/video tasks only: both | upload | record (how workers provide files)
  "title": "Submit 10 photos of your face", // Required
  "description": "<p>Take 10 clear photos from different angles...</p>", // Required, HTML allowed
  "submission_instructions": "Front, left, right, up, down and 5 more angles. No filters.", // Required
  "required_file_count": 10, // Required (1-200). Exact count for image/video/audio tasks, maximum for others
  "pay_rate": "0.50", // Required (minimum: 0.10)
  "total_availabilities": 100, // Required (10-20000)
  "length_in_minutes": 10, // Optional
  "countries": ["All"], // Required. ["All"] for every country, or ISO codes like ["US", "GB"]
  "excluded_countries": ["IN", "BD"], // Optional, only with ["All"]: every country except these
  "reference_upload_ids": [12, 13], // Optional: sample/instructional media uploaded via /api/ai-tasks/reference-uploads/
  "submission_fields": [ // Required for custom_data_collection only: the worker form, in display order (max 30)
    { "type": "select", "label": "Category", "required": true, "options": ["Electricity", "Insurance"] },
    // Dependent dropdown: its options follow the answer to an earlier plain dropdown.
    // parent_key is that dropdown's position as "field_<n>" (the first field is field_1).
    // options_by_parent needs a list (1-1000 options) for every parent option, 5000 options in total.
    // Workers can only submit an option listed under the parent option they chose.
    { "type": "select", "label": "Biller / Company Name", "required": true, "parent_key": "field_1",
      "options_by_parent": { "Electricity": ["B.E.S.T Mumbai", "TP Ajmer Distribution Ltd"], "Insurance": ["HDFC Life Insurance"] } },
    { "type": "image", "label": "Bill screenshot", "required": true, "min_files": 1, "max_files": 1, "help_text": "Upload the original SMS screenshot" },
    { "type": "consent", "label": "I consent to share this data", "required": true }
    // type: short_text | long_text | select | datetime | consent | image | audio | video
  ]
}

// Alternatively send multipart/form-data with up to 30 reference_images (JPG, PNG or WEBP, 5MB each)
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/ai-tasks/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "task_type": "image_collection",
        "title": "Submit 10 photos of your face",
        "description": "<p>Take 10 clear photos of your face from different angles.</p>",
        "submission_instructions": "Front, left, right, up, down and 5 more angles. No filters.",
        "required_file_count": 10,
        "pay_rate": "0.50",
        "total_availabilities": 100,
        "length_in_minutes": 10,
        "countries": ["All"]
    }
)
task = response.json()
print(f"Task created: {task['task_id']}")
JSON
// 201 Created
{
  "message": "AI task created successfully",
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "Active"
}

400—Datos no válidos, saldo insuficiente o la cuenta no tiene ningún depósito

401—Clave API no válida o ausente

403—Las tareas de IA aún no están habilitadas para esta cuenta

Lista todas las tareas de IA que has creado con el número de envíos.

Solicitud
Sin parámetros
python
import requests

response = requests.get(
    "https://api.rapidworkers.io/api/ai-tasks/mine/",
    headers={"X-API-Key": "your_api_key_here"}
)
for task in response.json()["tasks"]:
    print(task["title"], task["pendingSubmissions"], "pending")
JSON
// 200 OK
{
  "tasks": [
    {
      "taskPublicId": "123e4567-e89b-12d3-a456-426614174000",
      "taskType": "image_collection",
      "title": "Submit 10 photos of your face",
      "pay": "0.50",
      "countries": ["All"],
      "lengthInMinutes": 10,
      "requiredFileCount": 10,
      "referenceImages": [],
      "completedCount": 12,
      "totalAvailabilities": 100,
      "pendingSubmissions": 3,
      "status": "Active",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ]
}

401—Clave API no válida o ausente

Obtiene una tarea de IA, incluidas sus reglas de envío e imágenes de referencia.

Parámetros de Ruta

task_idUUID
Solicitud
Sin parámetros
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/",
    headers={"X-API-Key": "your_api_key_here"}
)
task = response.json()["task"]
print(f"Approved: {task['approvedSubmissions']} / {task['totalAvailabilities']}")
JSON
// 200 OK
{
  "task": {
    "taskPublicId": "123e4567-e89b-12d3-a456-426614174000",
    "taskType": "image_collection",
    "title": "Submit 10 photos of your face",
    "description": "<p>Take 10 clear photos...</p>",
    "submissionInstructions": "Front, left, right, up, down and 5 more angles.",
    "pay": "0.50",
    "countries": ["All"],
    "requiredFileCount": 10,
    "referenceImages": ["https://.../example.jpg"],
    "rules": {
      "allowedTypes": ["image/heic", "image/heif", "image/jpeg", "image/png", "image/webp"],
      "maxBytes": 15728640,
      "exactCount": true,
      "textRequired": false,
      "fileCount": 10
    },
    "completedCount": 12,
    "totalAvailabilities": 100,
    "pendingSubmissions": 3,
    "approvedSubmissions": 9,
    "rejectedSubmissions": 1,
    "reservedAmount": "50.00",
    "paidOutAmount": "4.50",
    "status": "Active",
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

401—Clave API no válida o ausente

404—Tarea no encontrada

Lista los envíos de una tarea de IA con la respuesta escrita del trabajador y enlaces de descarga temporales para cada archivo. Los enlaces valen 1 hora.

Parámetros de Ruta

task_idUUID
statusstring

Pending, Approved, Rejected

python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/submissions/",
    headers={"X-API-Key": "your_api_key_here"},
    params={"status": "Pending"}
)
for submission in response.json()["submissions"]:
    for file in submission["files"]:
        data = requests.get(file["url"]).content  # download while the link is valid
        open(file["name"], "wb").write(data)
JSON
// 200 OK
{
  "task": { "taskPublicId": "123e4567-...", "title": "Submit 10 photos of your face", "status": "Active" },
  "submissions": [
    {
      "submissionId": 42,
      "userId": 1234,
      "userName": "Jane D.", // First name and last-name initial; employers never see a worker's email or full name
      "countryName": "Canada",
      "status": "Pending",
      "paymentStatus": "Not_Paid",
      "amountPaid": null,
      "textResponse": "",
      "notes": "",
      "fileCount": 10,
      "files": [
        {
          "id": 501,
          "name": "front.jpg",
          "contentType": "image/jpeg",
          "size": 2451234,
          "url": "https://bucket.s3.amazonaws.com/private/ai-tasks/...?X-Amz-Expires=3600&..." // Valid for 1 hour
        }
      ],
      "isBlocked": false,
      "submittedAt": "2025-01-16T08:12:00Z"
    }
  ]
}

401—Clave API no válida o ausente

403—Esta tarea no es tuya

404—Tarea no encontrada

Aprueba un envío de tarea de IA y paga al trabajador con los fondos reservados de la tarea.

Parámetros de Ruta

task_idUUID
submission_idinteger

Content-Type:application/json

JSON
{
  "notes": "Great photos, thank you", // Optional
  "tip": "2.00" // Optional: $0.01-$50.00 from your balance, paid to the worker in full with no fee
}
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
submission_id = 42
response = requests.post(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/submissions/{submission_id}/approve/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={"notes": "Great photos, thank you"}
)
print(response.json()["message"])
JSON
// 200 OK
{
  "success": true,
  "message": "Submission approved",
  "submission": {
    "submissionId": 42,
    "status": "Approved",
    "paymentStatus": "Paid",
    "amountPaid": "0.50"
  }
}

400—No hay suficientes fondos reservados para esta tarea, no hay saldo suficiente para la propina o la propina no es válida

401—Clave API no válida o ausente

403—Esta tarea no es tuya

404—Envío no encontrado

Rechaza un envío de tarea de IA con un motivo. El trabajador puede corregirlo y volver a enviar.

Parámetros de Ruta

task_idUUID
submission_idinteger

Content-Type:application/json

JSON
{
  "notes": "Photos are blurry, please retake in better light" // Required
}
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
submission_id = 42
response = requests.post(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/submissions/{submission_id}/reject/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={"notes": "Photos are blurry, please retake in better light"}
)
print(response.json()["message"])
JSON
// 200 OK
{
  "success": true,
  "message": "Submission rejected",
  "submission": {
    "submissionId": 42,
    "status": "Rejected",
    "notes": "Photos are blurry, please retake in better light"
  }
}

400—Falta el motivo del rechazo o el envío ya fue aprobado

401—Clave API no válida o ausente

403—Esta tarea no es tuya

404—Envío no encontrado

Genera URLs S3 prefirmadas para medios de muestra o instrucciones (imágenes, video, audio). Sube los bytes con PUT y pasa los ids devueltos como reference_upload_ids al crear la tarea.

Content-Type:application/json

JSON
{
  "files": [
    { "name": "sample.mp4", "content_type": "video/mp4", "size": 18422311 }, // Images up to 15MB, audio 50MB, video 500MB
    { "name": "front.jpg", "content_type": "image/jpeg", "size": 2451234 }
  ]
}
python
import requests

with open("sample.mp4", "rb") as f:
    data = f.read()

issued = requests.post(
    "https://api.rapidworkers.io/api/ai-tasks/reference-uploads/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={"files": [{"name": "sample.mp4", "content_type": "video/mp4", "size": len(data)}]}
).json()["uploads"][0]

requests.put(issued["url"], data=data, headers=issued["headers"]).raise_for_status()
upload_id = issued["uploadId"]  # pass in reference_upload_ids when creating the task
JSON
// 201 Created
{
  "uploads": [
    {
      "uploadId": 12,
      "name": "sample.mp4",
      "url": "https://bucket.s3.amazonaws.com/private/ai-task-references/...?X-Amz-Expires=3600&...",
      "headers": { "Content-Type": "video/mp4" }
    }
  ]
}

// PUT each file's bytes to its url with exactly those headers, then pass the uploadIds
// as reference_upload_ids when creating the task. URLs expire after 1 hour.

400—Tipo no admitido o archivo demasiado grande

401—Clave API no válida o ausente

429—Demasiadas subidas pendientes

Aprueba todos los envíos pendientes de una tarea de IA y paga a cada trabajador.

Parámetros de Ruta

task_idUUID

Content-Type:application/json

JSON
{
  "notes": "Thanks everyone", // Optional
  "quality_bands": ["good"] // Optional, surveys only: approve only the Pending responses in these quality bands
}
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.post(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/submissions/bulk_approve/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={}
)
print(response.json()["message"])
JSON
// 200 OK
{
  "success": true,
  "message": "12 submission(s) approved",
  "approved": 12,
  "error": null,
  "pendingLeft": 3 // Only with quality_bands: Pending responses in other bands, left for you to review
}

400—No hay suficientes fondos reservados, o se envió quality_bands en una tarea que no es una encuesta (código invalid_request)

401—Clave API no válida o ausente

403—Esta tarea no es tuya

404—Tarea no encontrada

Añade cupos a una tarea de IA. Se cobra a la tarifa de la tarea más comisión. Una tarea completada vuelve a estar activa.

Parámetros de Ruta

task_idUUID

Content-Type:application/json

JSON
{
  "additional_availabilities": 50 // Required. Charged at pay_rate x 50 plus commission
}
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.post(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/extend/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={"additional_availabilities": 50}
)
print(response.json()["task"]["totalAvailabilities"])
JSON
// 200 OK
{
  "message": "Task extended",
  "task": { "taskPublicId": "123e4567-...", "totalAvailabilities": 150, "status": "Active" }
}

400—Saldo insuficiente, la tarea no está activa o se supera el límite de 20,000

401—Clave API no válida o ausente

403—Esta tarea no es tuya

404—Tarea no encontrada

Edita una tarea de IA igual que se editan las campañas: la tarea se cancela y se reembolsan sus fondos no gastados, y una nueva versión con tus cambios la reemplaza (con un nuevo cargo). Envía todos los campos, como al crearla. Se permite mientras la tarea esté pendiente o activa, sin envíos pendientes de revisión y con menos de 10 ediciones.

Parámetros de Ruta

task_idUUID

Content-Type:application/json

JSON
// The same fields as creating a task (all of them, not just the changes), plus:
{
  "task_type": "image_collection",
  "title": "Submit 10 photos of your face",
  "description": "<p>Take 10 clear photos from different angles...</p>",
  "submission_instructions": "<p>Front, left, right, up, down and 5 more angles.</p>", // HTML allowed
  "required_file_count": 10,
  "pay_rate": "0.50",
  "total_availabilities": 100,
  "length_in_minutes": 10,
  "countries": ["All"],
  "keep_reference_ids": [41, 42] // Optional: ids of the task's current reference files to keep (from the task detail)
}
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
task = {
    "task_type": "image_collection",
    "title": "Submit 10 photos of your face",
    "description": "<p>Take 10 clear photos of your face from different angles.</p>",
    "submission_instructions": "Front, left, right, up, down and 5 more angles. No filters.",
    "required_file_count": 10,
    "pay_rate": "0.60",
    "total_availabilities": 100,
    "length_in_minutes": 10,
    "countries": ["All"]
}
response = requests.post(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/edit/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json=task
)
print(f"New version: {response.json()['task_id']}")
JSON
// 200 OK
{
  "message": "AI task updated successfully",
  "task_id": "9b2f6c1e-...", // The new version's id: use it from now on
  "status": "Active",
  "times_edited": 1
}

400—Datos no válidos, saldo insuficiente, envíos pendientes de revisión, la tarea no está pendiente ni activa, o ya se hicieron 10 ediciones

401—Clave API no válida o ausente

403—Esta tarea no es tuya

404—Tarea no encontrada

Detiene una tarea de IA y devuelve los fondos no retenidos por envíos pendientes. Estos aún se pueden aprobar y pagar.

Parámetros de Ruta

task_idUUID
Solicitud
Sin parámetros
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.post(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/cancel/",
    headers={"X-API-Key": "your_api_key_here"}
)
print(f"Refunded: {response.json()['refund']}")
JSON
// 200 OK
{
  "message": "Task canceled",
  "refund": "37.50",
  "task": { "taskPublicId": "123e4567-...", "status": "Canceled" }
}

400—La tarea ya está cancelada

401—Clave API no válida o ausente

403—Esta tarea no es tuya

404—Tarea no encontrada

Endpoints de Trabajos Predefinidos

Endpoints simplificados para tareas comunes de participación en redes sociales. Solo requiere un enlace y cantidad. Todos los trabajos preconfigurados tienen aprobación automática habilitada: las presentaciones se aprueban automáticamente y los trabajadores reciben el pago una vez que el trabajo alcanza su total de disponibilidades.

Crea un trabajo simplificado para obtener me gusta en publicaciones de Facebook. Solo requiere un enlace y cantidad. Precio automático: $0.05 por trabajo. Las presentaciones se aprueban automáticamente una vez que el trabajo está lleno.

Content-Type:application/json

JSON
{
  "link": "https://facebook.com/post/123", // Required
  "quantity": 50, // Required (minimum: 6)
  "countries": ["US", "GB"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/facebook-likes/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://facebook.com/post/123",
        "quantity": 50  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "2.50"
}

400—Datos no válidos, saldo insuficiente o cantidad inferior al mínimo (10)

401—Clave API no válida o ausente

Crea un trabajo simplificado para obtener compartidos en publicaciones de Facebook. Solo requiere un enlace y cantidad. Precio automático: $0.05 por trabajo. Las presentaciones se aprueban automáticamente una vez que el trabajo está lleno.

Content-Type:application/json

JSON
{
  "link": "https://facebook.com/post/123", // Required
  "quantity": 25, // Required (minimum: 6)
  "countries": ["US", "CA"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/facebook-shares/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://facebook.com/post/123",
        "quantity": 25  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "1.25"
}

400—Datos no válidos, saldo insuficiente o cantidad inferior al mínimo (10)

401—Clave API no válida o ausente

Crea una tarea de entrenamiento de IA lista para usar en la que cada trabajador envía fotos de su rostro desde distintos ángulos. Solo requiere el número de trabajadores. Por defecto: 10 fotos por trabajador a $0.10.

Content-Type:application/json

JSON
{
  "quantity": 50, // Required: number of workers (10-20000)
  "rate": "0.25", // Optional (default: 0.10, minimum: 0.10)
  "required_file_count": 10, // Optional (default: 10, maximum: 200) photos per worker
  "extra_instructions": "Wear no glasses in any photo.", // Optional, appended to the standard instructions
  "countries": ["US", "GB"] // Omit for all countries
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/ai-image-collection/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "quantity": 50,  # Minimum: 10
        "required_file_count": 10,
        "extra_instructions": "Wear no glasses in any photo."
    }
)
task = response.json()
print(f"Task created: {task['task_id']}")
JSON
// 201 Created
{
  "message": "Job created successfully",
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "Active",
  "total_cost": "12.50"
}

400—Datos no válidos, saldo insuficiente o cantidad inferior al mínimo (10)

401—Clave API no válida o ausente

403—Las tareas de IA aún no están habilitadas para esta cuenta

Crea una tarea de entrenamiento de IA lista para usar en la que cada trabajador graba clips de voz cortos en su navegador. Solo requiere el número de trabajadores. Por defecto: 5 clips por trabajador a $0.10.

Content-Type:application/json

JSON
{
  "quantity": 50, // Required: number of workers (10-20000)
  "rate": "0.25", // Optional (default: 0.10, minimum: 0.10)
  "required_file_count": 5, // Optional (default: 5, maximum: 200) clips per worker
  "capture_mode": "both", // Optional: both | upload | record
  "extra_instructions": "Read these sentences aloud: ...", // Optional, appended to the standard instructions
  "countries": ["US", "GB"] // Omit for all countries
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/ai-audio-collection/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "quantity": 50,  # Minimum: 10
        "required_file_count": 5,
        "extra_instructions": "Read these sentences aloud: The quick brown fox..."
    }
)
task = response.json()
print(f"Task created: {task['task_id']}")
JSON
// 201 Created
{
  "message": "Job created successfully",
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "Active",
  "total_cost": "12.50"
}

400—Datos no válidos, saldo insuficiente o cantidad inferior al mínimo (10)

401—Clave API no válida o ausente

403—Las tareas de IA aún no están habilitadas para esta cuenta

Crea un trabajo simplificado para obtener me gusta en publicaciones de Instagram. Solo requiere un enlace y cantidad. Precio automático: $0.05 por trabajo. Las presentaciones se aprueban automáticamente una vez que el trabajo está lleno.

Content-Type:application/json

JSON
{
  "link": "https://instagram.com/ABC123", // Required
  "quantity": 100, // Required (minimum: 6)
  "countries": ["US", "GB"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/instagram-likes/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://instagram.com/ABC123",
        "quantity": 100  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "5.00"
}

400—Datos no válidos, saldo insuficiente o cantidad inferior al mínimo (10)

401—Clave API no válida o ausente

Crea un trabajo simplificado para ganar seguidores de Instagram. Solo requiere un enlace y cantidad. Precio automático: $0.05 por trabajo. Las presentaciones se aprueban automáticamente una vez que el trabajo está lleno.

Content-Type:application/json

JSON
{
  "link": "https://instagram.com/username", // Required
  "quantity": 50, // Required (minimum: 6)
  "countries": ["US", "CA"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/instagram-followers/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://instagram.com/username",
        "quantity": 50  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "2.50"
}

400—Datos no válidos, saldo insuficiente o cantidad inferior al mínimo (10)

401—Clave API no válida o ausente

Crea un trabajo simplificado para obtener me gusta en publicaciones de Twitter/X. Solo requiere un enlace y cantidad. Precio automático: $0.05 por trabajo. Las presentaciones se aprueban automáticamente una vez que el trabajo está lleno.

Content-Type:application/json

JSON
{
  "link": "https://twitter.com/user/status/123", // Required
  "quantity": 75, // Required (minimum: 6)
  "countries": ["US", "GB"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/twitter-likes/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://twitter.com/user/status/123",
        "quantity": 75  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "3.75"
}

400—Datos no válidos, saldo insuficiente o cantidad inferior al mínimo (10)

401—Clave API no válida o ausente

Crea un trabajo simplificado para ganar seguidores de Twitter/X. Solo requiere un enlace y cantidad. Precio automático: $0.05 por trabajo. Las presentaciones se aprueban automáticamente una vez que el trabajo está lleno.

Content-Type:application/json

JSON
{
  "link": "https://twitter.com/username", // Required
  "quantity": 50, // Required (minimum: 6)
  "countries": ["US", "CA"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/twitter-followers/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://twitter.com/username",
        "quantity": 50  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "2.50"
}

400—Datos no válidos, saldo insuficiente o cantidad inferior al mínimo (10)

401—Clave API no válida o ausente

Crea un trabajo simplificado para obtener retweets de Twitter/X. Solo requiere un enlace y cantidad. Precio automático: $0.05 por trabajo. Las presentaciones se aprueban automáticamente una vez que el trabajo está lleno.

Content-Type:application/json

JSON
{
  "link": "https://twitter.com/user/status/123", // Required
  "quantity": 30, // Required (minimum: 6)
  "countries": ["US", "GB"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/twitter-retweets/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://twitter.com/user/status/123",
        "quantity": 30  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "1.50"
}

400—Datos no válidos, saldo insuficiente o cantidad inferior al mínimo (10)

401—Clave API no válida o ausente

Crea un trabajo simplificado para obtener reseñas de Trustpilot. Solo requiere un enlace y cantidad. Precio automático: $0.05 por trabajo. Las presentaciones se aprueban automáticamente una vez que el trabajo está lleno.

Content-Type:application/json

JSON
{
  "link": "https://trustpilot.com/review/example.com", // Required
  "quantity": 20, // Required (minimum: 6)
  "countries": ["US", "CA"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/trustpilot-reviews/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://trustpilot.com/review/example.com",
        "quantity": 20  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "1.00"
}

400—Datos no válidos, saldo insuficiente o cantidad inferior al mínimo (10)

401—Clave API no válida o ausente

Crea un trabajo simplificado para obtener votos positivos de 9GAG. Solo requiere un enlace y cantidad. Precio automático: $0.05 por trabajo. Las presentaciones se aprueban automáticamente una vez que el trabajo está lleno.

Content-Type:application/json

JSON
{
  "link": "https://9gag.com/gag/abc123", // Required
  "quantity": 50, // Required (minimum: 6)
  "countries": ["US", "GB"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/9gag-upvotes/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://9gag.com/gag/abc123",
        "quantity": 50  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "2.50"
}

400—Datos no válidos, saldo insuficiente o cantidad inferior al mínimo (10)

401—Clave API no válida o ausente

Crea un trabajo simplificado para obtener me gusta en videos de YouTube. Solo requiere un enlace y cantidad. Precio automático: $0.05 por trabajo. Las presentaciones se aprueban automáticamente una vez que el trabajo está lleno.

Content-Type:application/json

JSON
{
  "link": "https://youtube.com/watch?v=abc123", // Required
  "quantity": 100, // Required (minimum: 6)
  "countries": ["US", "CA"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/youtube-likes/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://youtube.com/watch?v=abc123",
        "quantity": 100  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "5.00"
}

400—Datos no válidos, saldo insuficiente o cantidad inferior al mínimo (10)

401—Clave API no válida o ausente

Manejo de Errores

Todos los errores de API siguen un formato consistente:

JSON
{
  "error": "Error message describing what went wrong"
}

Códigos de Estado HTTP Comunes:

Código de estadoEstadoDescripción
200OKSolicitud exitosa
201CreatedRecurso creado exitosamente
400Bad RequestDatos de solicitud inválidos
401UnauthorizedClave API faltante o inválida
403ForbiddenPermisos insuficientes
404Not FoundRecurso no encontrado
429Rate LimitedLímite de tasa excedido (1,000/hora)
500Server ErrorError del servidor