# Buscar proyectos de investigación

URL canónica: https://sosoapi.ai/es/docs/api/research-api-projects-query

Contrato: sha256:ab393e91e9b7f18a

Buscar proyectos de Research con paginación UUID; los elementos guardados no disponibles no contienen texto obsoleto. Requiere agent:research.

POST /research-api/projects/query

## Autenticación y permisos

- **Clases de credenciales aceptadas:** user_session, delegated_oauth, personal_access_token

- **Capacidad delegada:** agent:research

- **Rol mínimo del espacio de trabajo:** viewer

- **Alcance del acceso:** Recursos a los que este usuario está autorizado a acceder

- **Se requiere consentimiento para todos los espacios de trabajo:** No

- **Cambia el estado:** No

- **Cuando la operación se completa:** datos exactos de recurso Research autorizados actualmente

Un token solo puede usar los derechos de su propietario. Cada solicitud comprueba pertenencia al espacio, propiedad del recurso, espacios elegidos y capacidades concedidas. Los perfiles core y full cambian qué herramientas se muestran; no conceden acceso.

## Campos de solicitud

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "query": {
      "default": "",
      "type": "string",
      "maxLength": 200
    },
    "archived": {
      "default": false,
      "type": "boolean"
    },
    "cursor": {
      "description": "Continue after this Research record UUID in ascending UUID order; the marker includes unavailable library slots.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "limit": {
      "default": 25,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "workspace_id"
  ],
  "additionalProperties": false
}
```

## Respuesta y finalización

Estados HTTP de éxito: 200

Una respuesta HTTP exitosa puede indicar aceptación, no finalización. Para trabajo en segundo plano, guarda el ID devuelto y consulta la misma operación hasta que termine. Una publicación programada o aceptada solo está publicada cuando la plataforma lo confirma; un tiempo de espera agotado en el cliente no determina el resultado.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "items": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "revision": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "archived": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
            "format": "date-time"
          },
          "content": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "question": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "purpose": {
                "type": "string",
                "maxLength": 1000
              },
              "audience": {
                "type": "string",
                "maxLength": 2000
              },
              "brands": {
                "maxItems": 20,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "name": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    },
                    "terms": {
                      "minItems": 1,
                      "maxItems": 20,
                      "type": "array",
                      "items": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 100
                      }
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "terms"
                  ]
                }
              },
              "scope": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "excluded_terms": {
                    "maxItems": 50,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    }
                  },
                  "platforms": {
                    "maxItems": 7,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "threads",
                        "instagram",
                        "facebook",
                        "youtube",
                        "x",
                        "reddit",
                        "web"
                      ]
                    }
                  },
                  "source_categories": {
                    "minItems": 1,
                    "maxItems": 3,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "your_accounts",
                        "public_posts",
                        "team_notes"
                      ]
                    }
                  },
                  "languages": {
                    "maxItems": 18,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 35
                    }
                  },
                  "since": {
                    "anyOf": [
                      {
                        "type": "string",
                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
                        "format": "date-time"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "until": {
                    "anyOf": [
                      {
                        "type": "string",
                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
                        "format": "date-time"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "query",
                  "excluded_terms",
                  "platforms",
                  "source_categories",
                  "languages",
                  "since",
                  "until"
                ]
              }
            },
            "required": [
              "title",
              "question",
              "purpose",
              "audience",
              "brands",
              "scope"
            ]
          }
        },
        "required": [
          "id",
          "workspace_id",
          "revision",
          "archived",
          "created_at",
          "updated_at",
          "content"
        ]
      }
    },
    "unavailable_items": {
      "default": [],
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "revision": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "archived": {
            "type": "boolean"
          },
          "availability": {
            "type": "string",
            "const": "dependency_unavailable"
          }
        },
        "required": [
          "id",
          "workspace_id",
          "revision",
          "archived",
          "availability"
        ]
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        {
          "type": "null"
        }
      ],
      "description": "Last consumed record UUID across items and unavailable_items when another slot exists; null at the end."
    }
  },
  "required": [
    "items",
    "unavailable_items",
    "next_cursor"
  ]
}
```

## Errores y reintentos seguros

Comprueba el estado HTTP y el cuerpo de respuesta. Un error de validación 400 puede contener un ZodError; los errores del controlador usan los campos error, message y code. Conserva request_id o x-request-id para el diagnóstico, sin credenciales. Corrige los errores de acceso 401/403 antes de reintentar y respeta Retry-After para 429. Si una escritura es incierta o devuelve 5xx, consulta primero el resultado existente. Reutiliza una clave de idempotencia solo donde se admita; el comportamiento de reintento varía por operación y no garantiza una entrega exactamente una vez.

## Ejemplos

Estos ejemplos usan valores ficticios comprobados con los esquemas. Sustituye los IDs por otros autorizados, los archivos multimedia por recursos listos y las fechas por tu hora de publicación confirmada. Comprueba la elegibilidad de la cuenta antes de enviar una escritura. Esta página no envía solicitudes API.

Establece SOSOAPI_ACCESS_TOKEN en tu servidor con una credencial aceptada por esta operación y mantenla fuera del código del navegador. Para un agente de IA, usa sosoapi auth login para iniciar sesión en el navegador y deja a la CLI renovar sus credenciales.

request.json

```json
{
  "workspace_id": "11111111-1111-4111-8111-111111111111"
}
```

cURL

```bash
curl --request POST \
  "https://gqeshlawtcexsapabaui.supabase.co/functions/v1/research-api/projects/query" \
  -H "Authorization: Bearer $SOSOAPI_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json
```

JavaScript

```js
// Server-side JavaScript. Do not print tokens or credential-bearing responses.
const token = process.env.SOSOAPI_ACCESS_TOKEN;
if (!token) throw new Error("Set an accepted credential for this operation");
const response = await fetch("https://gqeshlawtcexsapabaui.supabase.co/functions/v1/research-api/projects/query", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: "Bearer " + token },
  body: JSON.stringify({
  "workspace_id": "11111111-1111-4111-8111-111111111111"
})
});
const result = await response.json();
// Check response.ok, the operation-specific body and completion state before continuing.
```

CLI

```bash
npx sosoapi api post /research-api/projects/query < request.json
```

Ejemplo de respuesta sintética

```json
{
  "items": [],
  "unavailable_items": [],
  "next_cursor": null
}
```

## Herramientas y guías relacionadas

MCP: sosoapi_research_projects_query

[Referencia de API](https://sosoapi.ai/es/docs/api)